@defra/forms-model 3.0.2

package/src/conditions/inline-condition-values.ts

@@ -0,0 +1,153 @@
+const conditionValueFactories = {}
+
+class Registration {
+  type
+
+  constructor(type, factory) {
+    conditionValueFactories[type] = factory
+    this.type = type
+  }
+}
+
+export class AbstractConditionValue {
+  type
+
+  constructor(registration) {
+    if (new.target === AbstractConditionValue) {
+      throw new TypeError('Cannot construct ConditionValue instances directly')
+    }
+    if (!(registration instanceof Registration)) {
+      throw new TypeError(
+        'You must register your value type! Call registerValueType!'
+      )
+    }
+    this.type = registration.type
+  }
+
+  toPresentationString() {}
+  toExpression() {}
+}
+
+const valueType = registerValueType('Value', (obj) => ConditionValue.from(obj))
+export class ConditionValue extends AbstractConditionValue {
+  value
+  display
+
+  constructor(value, display) {
+    super(valueType)
+    if (!value || typeof value !== 'string') {
+      throw Error(`value ${value} is not valid`)
+    }
+    if (display && typeof display !== 'string') {
+      throw Error(`display ${display} is not valid`)
+    }
+    this.value = value
+    this.display = display || value
+  }
+
+  toPresentationString() {
+    return this.display
+  }
+
+  toExpression() {
+    return this.value
+  }
+
+  static from(obj) {
+    return new ConditionValue(obj.value, obj.display)
+  }
+
+  clone() {
+    return ConditionValue.from(this)
+  }
+}
+
+export const dateDirections = {
+  FUTURE: 'in the future',
+  PAST: 'in the past'
+}
+
+export const dateUnits = {
+  YEARS: { display: 'year(s)', value: 'years' },
+  MONTHS: { display: 'month(s)', value: 'months' },
+  DAYS: { display: 'day(s)', value: 'days' }
+}
+export const timeUnits = {
+  HOURS: { display: 'hour(s)', value: 'hours' },
+  MINUTES: { display: 'minute(s)', value: 'minutes' },
+  SECONDS: { display: 'second(s)', value: 'seconds' }
+}
+export const dateTimeUnits = Object.assign({}, dateUnits, timeUnits)
+
+export const relativeTimeValueType = registerValueType('RelativeTime', (obj) =>
+  RelativeTimeValue.from(obj)
+)
+export class RelativeTimeValue extends AbstractConditionValue {
+  timePeriod
+  timeUnit
+  direction
+  timeOnly
+
+  constructor(timePeriod, timeUnit, direction, timeOnly = false) {
+    super(relativeTimeValueType)
+    if (typeof timePeriod !== 'string') {
+      throw Error(`time period ${timePeriod} is not valid`)
+    }
+    if (
+      !Object.values(dateTimeUnits)
+        .map((it) => it.value)
+        .includes(timeUnit)
+    ) {
+      throw Error(`time unit ${timeUnit} is not valid`)
+    }
+    if (!Object.values(dateDirections).includes(direction)) {
+      throw Error(`direction ${direction} is not valid`)
+    }
+    this.timePeriod = timePeriod
+    this.timeUnit = timeUnit
+    this.direction = direction
+    this.timeOnly = timeOnly
+  }
+
+  toPresentationString() {
+    return `${this.timePeriod} ${this.timeUnit} ${this.direction}`
+  }
+
+  toExpression() {
+    const timePeriod =
+      this.direction === dateDirections.PAST
+        ? 0 - Number(this.timePeriod)
+        : this.timePeriod
+    return this.timeOnly
+      ? `timeForComparison(${timePeriod}, '${this.timeUnit}')`
+      : `dateForComparison(${timePeriod}, '${this.timeUnit}')`
+  }
+
+  static from(obj) {
+    return new RelativeTimeValue(
+      obj.timePeriod,
+      obj.timeUnit,
+      obj.direction,
+      obj.timeOnly
+    )
+  }
+
+  clone() {
+    return RelativeTimeValue.from(this)
+  }
+}
+
+/**
+ * All value types should call this, and should be located in this file.
+ * Furthermore the types should be registered without the classes needing to be instantiated.
+ *
+ * Otherwise we can't guarantee they've been registered for deserialization before
+ * valueFrom is called
+ */
+function registerValueType(type, factory) {
+  return new Registration(type, factory)
+}
+
+export function valueFrom(obj) {
+  return conditionValueFactories[obj.type](obj)
+}

package/src/conditions/types.ts

@@ -0,0 +1,30 @@
+import { Condition } from './condition'
+import { ConditionRef } from './condition-ref'
+import { ConditionGroup } from './condition-group'
+
+export type ConditionsArray = (Condition | ConditionGroup | ConditionRef)[]
+
+export enum Coordinator {
+  AND = 'and',
+  OR = 'or'
+}
+
+export type DateTimeUnitValues =
+  | 'years'
+  | 'months'
+  | 'days'
+  | 'hours'
+  | 'minutes'
+  | 'seconds'
+
+export type DateUnits = {
+  YEARS: { display: 'year(s)'; value: 'years' }
+  MONTHS: { display: 'month(s)'; value: 'months' }
+  DAYS: { display: 'day(s)'; value: 'days' }
+}
+
+export type TimeUnits = {
+  HOURS: { display: 'hour(s)'; value: 'hours' }
+  MINUTES: { display: 'minute(s)'; value: 'minutes' }
+  SECONDS: { display: 'second(s)'; value: 'seconds' }
+}

package/src/data-model/conditions-wrapper.ts

@@ -0,0 +1,42 @@
+import { Condition } from '../conditions/condition'
+import { ConditionsModel } from '../conditions/condition-model'
+
+export type ConditionWrapperValue =
+  | string
+  | {
+      name: string
+      conditions: Condition[]
+    }
+
+export type ConditionRawData = {
+  name: string
+  displayName: string
+  value: ConditionWrapperValue
+}
+
+export class ConditionsWrapper {
+  name: string
+  displayName: string
+  value: ConditionWrapperValue
+
+  constructor(rawData: ConditionRawData) {
+    const { name, displayName, value } = rawData
+    this.displayName = displayName || name
+    this.value = value
+    this.name = name
+  }
+
+  get expression() {
+    if (typeof this.value === 'string') {
+      // Previously conditions were defined as strings, e.g: "section.age < 18"
+      // keep this so application can support legacy forms exports.
+      return this.value
+    }
+
+    return ConditionsModel.from(this.value).toExpression()
+  }
+
+  clone(): ConditionsWrapper {
+    return new ConditionsWrapper(this)
+  }
+}

package/src/data-model/index.ts

@@ -0,0 +1,3 @@
+export { InputWrapper } from './input-wrapper'
+export { ConditionsWrapper, ConditionRawData } from './conditions-wrapper'
+export { Page, Item, Section, List, ConfirmationPage } from './types'

package/src/data-model/input-wrapper.ts

@@ -0,0 +1,40 @@
+import { clone } from '../utils/helpers'
+import { ComponentDef } from '../components/types'
+import { Page } from './types'
+
+export class InputWrapper {
+  name: string | undefined = undefined
+  title: string | undefined = undefined
+  type: string | undefined = undefined
+  propertyPath: string | undefined
+  #parentItemName: string | undefined
+  page: Page
+
+  constructor(
+    rawData: ComponentDef,
+    page: Page,
+    options: { ignoreSection?: boolean; parentItemName?: string }
+  ) {
+    Object.assign(this, rawData)
+    const myPage = clone(page)
+
+    delete myPage.components
+
+    this.page = myPage
+    this.propertyPath =
+      !options.ignoreSection && page.section
+        ? `${page.section}.${this.name}`
+        : this.name
+    this.#parentItemName = options.parentItemName
+  }
+
+  get displayName(): string | undefined {
+    const titleWithContext = this.#parentItemName
+      ? `${this.title} under ${this.#parentItemName}`
+      : this.title
+
+    return this.page.section
+      ? `${titleWithContext} in ${this.page.section}`
+      : titleWithContext
+  }
+}

package/src/data-model/types.ts

@@ -0,0 +1,179 @@
+import { ConditionRawData } from '.'
+import { ComponentDef } from '../components/types'
+
+type Toggleable<T> = boolean | T
+
+export interface Next {
+  path: string
+  condition?: string
+}
+export type Link = Next
+
+export interface Page {
+  title: string
+  path: string
+  controller: string
+  components?: ComponentDef[]
+  section: string // the section ID
+  next?: { path: string; condition?: string }[]
+}
+
+export interface RepeatingFieldPage extends Page {
+  controller: 'RepeatingFieldPageController'
+  options: {
+    summaryDisplayMode?: {
+      samePage?: boolean
+      separatePage?: boolean
+      hideRowTitles?: boolean
+    }
+    customText?: {
+      separatePageTitle?: string
+    }
+  }
+}
+
+export interface Section {
+  name: string
+  title: string
+  hideTitle: boolean
+}
+
+export interface Item {
+  text: string
+  value: string | number | boolean
+  description?: string
+  condition?: string
+}
+
+export interface List {
+  name: string
+  title: string
+  type: 'string' | 'number' | 'boolean'
+  items: Item[]
+}
+
+export interface Feedback {
+  feedbackForm?: boolean
+  url?: string
+  emailAddress?: string
+}
+
+export type PhaseBanner = {
+  phase?: 'alpha' | 'beta'
+  feedbackUrl?: string
+}
+
+export type MultipleApiKeys = {
+  test?: string
+  production?: string
+}
+
+export enum OutputType {
+  Email = 'email',
+  Notify = 'notify',
+  Webhook = 'webhook'
+}
+
+export type EmailOutputConfiguration = {
+  emailAddress: string
+}
+
+export type NotifyOutputConfiguration = {
+  apiKey: string
+  templateId: string
+  emailField: string
+  personalisation: string[]
+  personalisationFieldCustomisation?: {
+    [personalisationName: string]: string[]
+  }
+  addReferencesToPersonalisation?: boolean
+  emailReplyToIdConfiguration?: {
+    emailReplyToId: string
+    condition?: string | undefined
+  }[]
+}
+
+export type WebhookOutputConfiguration = {
+  url: string
+}
+
+export type OutputConfiguration =
+  | EmailOutputConfiguration
+  | NotifyOutputConfiguration
+  | WebhookOutputConfiguration
+
+export type Output = {
+  name: string
+  title: string
+  type: OutputType
+  outputConfiguration: OutputConfiguration
+}
+
+export type ConfirmationPage = {
+  customText: {
+    title: string
+    paymentSkipped: Toggleable<string>
+    nextSteps: Toggleable<string>
+  }
+  components: ComponentDef[]
+}
+
+export type PaymentSkippedWarningPage = {
+  customText: {
+    title: string
+    caption: string
+    body: string
+  }
+}
+
+export type SpecialPages = {
+  confirmationPage?: ConfirmationPage
+  paymentSkippedWarningPage?: PaymentSkippedWarningPage
+}
+
+export function isMultipleApiKey(
+  payApiKey: string | MultipleApiKeys | undefined
+): payApiKey is MultipleApiKeys {
+  const obj = payApiKey as MultipleApiKeys
+  return obj.test !== undefined || obj.production !== undefined
+}
+
+export type Fee = {
+  description: string
+  amount: number
+  multiplier?: string
+  condition?: string
+  prefix?: string
+}
+
+export type FeeOptions = {
+  paymentReferenceFormat?: string
+  payReturnUrl?: string
+  allowSubmissionWithoutPayment: boolean
+  maxAttempts: number
+  customPayErrorMessage?: string
+  showPaymentSkippedWarningPage: boolean
+}
+
+/**
+ * `FormDefinition` is a typescript representation of `Schema`
+ */
+export type FormDefinition = {
+  pages: Array<Page | RepeatingFieldPage>
+  conditions: ConditionRawData[]
+  lists: List[]
+  sections: Section[]
+  startPage?: Page['path'] | undefined
+  name?: string | undefined
+  feedback?: Feedback
+  phaseBanner?: PhaseBanner
+  fees: Fee[]
+  skipSummary?: boolean | undefined
+  outputs: Output[]
+  declaration?: string | undefined
+  metadata?: Record<string, any>
+  payApiKey?: string | MultipleApiKeys | undefined
+  specialPages?: SpecialPages
+  paymentReferenceFormat?: string
+  feeOptions: FeeOptions
+}

package/src/form/form-configuration.ts

@@ -0,0 +1,21 @@
+export class FormConfiguration {
+  Key: string
+  DisplayName: string
+  LastModified: string | undefined
+  feedbackForm: boolean | undefined
+
+  constructor(
+    Key: string,
+    DisplayName?: string,
+    LastModified?: string,
+    feedbackForm?: boolean
+  ) {
+    if (!Key) {
+      throw Error('Form configuration must have a key')
+    }
+    this.Key = Key
+    this.DisplayName = DisplayName || Key
+    this.LastModified = LastModified
+    this.feedbackForm = feedbackForm || false
+  }
+}

package/src/form/index.ts

@@ -0,0 +1 @@
+export { FormConfiguration } from './form-configuration'

package/src/index.ts

@@ -0,0 +1,11 @@
+export { Schema, componentSchema } from './schema'
+export { ConditionRawData, ConditionsWrapper } from './data-model'
+export { Logger } from './utils/logger'
+export { FormConfiguration } from './form'
+export { ComponentTypes, ConditionalComponentTypes } from './components'
+export * from './components/types'
+export * from './conditions'
+export * from './utils/helpers'
+export * from './migration'
+export * from './data-model/types'
+export { whichMigrations } from './migration/whichMigrations'

package/src/migration/index.ts

@@ -0,0 +1 @@
+export { whichMigrations } from './whichMigrations'

package/src/migration/migration.0-2.ts

@@ -0,0 +1,29 @@
+import { MigrationScript } from './types'
+
+function needsUpgrade(data) {
+  return !!(data.pages ?? [])
+    .flatMap((page) => page.components)
+    .find((component) => component.options?.list)
+}
+
+export function migrate(data): MigrationScript {
+  if (!needsUpgrade(data)) {
+    return { ...data, version: 2 }
+  }
+  const { pages } = data
+  const newPages = pages.flatMap((page) => {
+    return page.components.map((component) => {
+      if (!component.options?.list) {
+        return component
+      }
+      const { list, ...rest } = component.options
+      return { ...component, list, options: { ...rest } }
+    })
+  })
+
+  return {
+    ...data,
+    pages: newPages,
+    version: 2
+  }
+}

package/src/migration/migration.1-2.ts

@@ -0,0 +1,105 @@
+import { MigrationScript } from './types'
+import { nanoid } from '../utils/helpers'
+
+/**
+ * @private
+ * StaticItem is a deprecated Type.
+ * It should only be used for aiding migration scripts.
+ */
+type StaticItem = {
+  label: string
+  value: string | number | boolean
+  hint?: string
+  condition?: string
+}
+
+/**
+ * @private
+ * StaticComponentValues is a deprecated Type.
+ * It should only be used for aiding migration scripts.
+ */
+type StaticComponentValues = {
+  list: any
+  type: 'static' | 'listRef'
+  valueType: string | number
+  items: StaticItem[]
+}
+
+type Item = {
+  title: string
+  value: any
+  conditions?: any
+  hint?: string
+}
+
+function recastItem({ label, value, condition, hint }: StaticItem) {
+  const item: Item = {
+    title: label,
+    value
+  }
+
+  condition && (item.conditions = condition)
+  hint && (item.hint = hint)
+  return item
+}
+
+function addListId(component: { values: StaticComponentValues }) {
+  if (!component.values) {
+    return component
+  }
+  const { values } = component
+  return {
+    ...component,
+    list: values.type === 'listRef' ? values.list : nanoid()
+  }
+}
+
+function migratePage(page) {
+  return {
+    ...page,
+    components: page.components.map(addListId)
+  }
+}
+
+function removeValues(page) {
+  return {
+    ...page,
+    components: page.components.map((component) => {
+      const { values, ...rest } = component
+      return {
+        ...rest
+      }
+    })
+  }
+}
+
+function needsUpgrade(data) {
+  return !!data.pages
+    .flatMap((page) => page.components)
+    .find((component) => component.values)
+}
+
+export function migrate(data): MigrationScript {
+  if (!needsUpgrade(data)) {
+    return { ...data, version: 2 }
+  }
+  const pages = data.pages.map(migratePage)
+  const componentsWithList = pages.flatMap((page) =>
+    page.components.filter((c) => c.values?.items)
+  )
+
+  const valuesAsLists = componentsWithList.map((component) => {
+    return {
+      title: component.title,
+      name: component.list,
+      items: component.values.items.map((item) => recastItem(item))
+    }
+  })
+
+  return {
+    ...data,
+    pages: pages.map(removeValues),
+    lists: [...(data.lists ?? []), ...valuesAsLists],
+    version: 2
+  }
+}

package/src/migration/types.ts

@@ -0,0 +1 @@
+export type MigrationScript = (data: Object) => Object

package/src/migration/whichMigrations.ts

@@ -0,0 +1,23 @@
+import { migrate as V0_TO_V2 } from './migration.0-2'
+import { migrate as V1_TO_V2 } from './migration.1-2'
+import { MigrationScript } from './types'
+
+/**
+ * Returns which migrations that should be run against your Object with the given version
+ * @param version
+ */
+export function whichMigrations(version: number) {
+  const migrations = new Set<MigrationScript>()
+  switch (version) {
+    case 0:
+      migrations.add(V0_TO_V2)
+      /**
+       * we are skipping v1 entirely. If we weren't you would do migrations.add([V1_TO_V2, V2_TO_V3]) for example.
+       */
+      break
+    case 1:
+      migrations.add(V1_TO_V2)
+      break
+  }
+  return migrations
+}

package/src/schema/index.ts

@@ -0,0 +1 @@
+export { Schema, componentSchema } from './schema'