@duffcloudservices/site-forms 0.1.0

package/src/composables/useDcsForm.ts

@@ -0,0 +1,201 @@
+import { computed, reactive, ref, type ComputedRef, type Ref } from 'vue'
+import type {
+  PortalFormDefinition,
+  PortalFormField,
+  PortalFormStep,
+  FormErrors,
+  FormValues,
+} from '../types'
+import {
+  hasErrors,
+  isFieldVisible,
+  validateForm,
+} from './useFormValidation'
+
+export interface UseDcsFormOptions {
+  definition: PortalFormDefinition
+}
+
+export interface UseDcsFormReturn {
+  values: FormValues
+  errors: Ref<FormErrors>
+  touched: Ref<Record<string, boolean>>
+  submitting: Ref<boolean>
+  submitted: Ref<boolean>
+  submitError: Ref<string | null>
+  /** All fields, with layout-only types preserved. */
+  fields: ComputedRef<PortalFormField[]>
+  /** Steps if multi-step, else null. */
+  steps: ComputedRef<PortalFormStep[] | null>
+  currentStepIndex: Ref<number>
+  currentStep: ComputedRef<PortalFormStep | null>
+  currentStepFields: ComputedRef<PortalFormField[]>
+  isFirstStep: ComputedRef<boolean>
+  isLastStep: ComputedRef<boolean>
+  visibleFields: ComputedRef<PortalFormField[]>
+  /** Sets a field value and clears that field's error. */
+  setValue: (id: string, value: unknown) => void
+  /** Marks a field as touched + revalidates only that field's row. */
+  touch: (id: string) => void
+  /** Validates the current step (multi-step) or the entire form. */
+  validateCurrentScope: () => boolean
+  validateAll: () => boolean
+  next: () => boolean
+  prev: () => void
+  reset: () => void
+  /** Returns the values that should actually be submitted (visible only). */
+  collectSubmissionValues: () => FormValues
+}
+
+function defaultsFor(def: PortalFormDefinition): FormValues {
+  const out: FormValues = {}
+  for (const f of def.fields) {
+    if (f.defaultValue !== undefined) {
+      out[f.id] = f.defaultValue as unknown
+    } else if (f.type === 'checkbox') {
+      out[f.id] = false
+    } else if (f.type === 'multiselect' || f.type === 'checkbox-group') {
+      out[f.id] = [] as string[]
+    } else {
+      out[f.id] = ''
+    }
+  }
+  return out
+}
+
+export function useDcsForm(opts: UseDcsFormOptions): UseDcsFormReturn {
+  const { definition } = opts
+  const values = reactive<FormValues>(defaultsFor(definition))
+  const errors = ref<FormErrors>({})
+  const touched = ref<Record<string, boolean>>({})
+  const submitting = ref(false)
+  const submitted = ref(false)
+  const submitError = ref<string | null>(null)
+  const currentStepIndex = ref(0)
+
+  const fields = computed(() => definition.fields)
+  const steps = computed<PortalFormStep[] | null>(() =>
+    definition.steps && definition.steps.length > 0 ? definition.steps : null,
+  )
+  const currentStep = computed<PortalFormStep | null>(() => {
+    const s = steps.value
+    return s ? (s[currentStepIndex.value] ?? null) : null
+  })
+  const currentStepFields = computed<PortalFormField[]>(() => {
+    const step = currentStep.value
+    if (!step) return definition.fields
+    const ids = new Set(step.fieldIds)
+    return definition.fields.filter((f) => ids.has(f.id))
+  })
+  const isFirstStep = computed(() => currentStepIndex.value === 0)
+  const isLastStep = computed(() => {
+    const s = steps.value
+    return !s || currentStepIndex.value >= s.length - 1
+  })
+  const visibleFields = computed(() =>
+    currentStepFields.value.filter((f) => isFieldVisible(f, values as FormValues)),
+  )
+
+  function setValue(id: string, value: unknown): void {
+    ;(values as FormValues)[id] = value
+    if (errors.value[id]) {
+      errors.value = { ...errors.value, [id]: undefined }
+    }
+  }
+
+  function touch(id: string): void {
+    touched.value = { ...touched.value, [id]: true }
+  }
+
+  function validateScope(scopeFieldIds?: string[]): boolean {
+    const next = validateForm(definition, values as FormValues, scopeFieldIds)
+    // Merge with existing errors but only for the validated scope so we
+    // don't wipe out errors from other steps.
+    if (scopeFieldIds) {
+      const merged = { ...errors.value }
+      for (const id of scopeFieldIds) {
+        merged[id] = next[id]
+      }
+      errors.value = merged
+    } else {
+      errors.value = next
+    }
+    return !hasErrors(errors.value)
+  }
+
+  function validateCurrentScope(): boolean {
+    const scope = currentStep.value?.fieldIds
+    return validateScope(scope)
+  }
+
+  function validateAll(): boolean {
+    return validateScope()
+  }
+
+  function next(): boolean {
+    if (!steps.value) return false
+    if (!validateCurrentScope()) return false
+    if (currentStepIndex.value < steps.value.length - 1) {
+      currentStepIndex.value++
+      return true
+    }
+    return false
+  }
+
+  function prev(): void {
+    if (currentStepIndex.value > 0) currentStepIndex.value--
+  }
+
+  function reset(): void {
+    const fresh = defaultsFor(definition)
+    for (const k of Object.keys(values as object)) {
+      delete (values as FormValues)[k]
+    }
+    Object.assign(values as FormValues, fresh)
+    errors.value = {}
+    touched.value = {}
+    submitting.value = false
+    submitted.value = false
+    submitError.value = null
+    currentStepIndex.value = 0
+  }
+
+  function collectSubmissionValues(): FormValues {
+    const out: FormValues = {}
+    for (const f of definition.fields) {
+      if (
+        f.type === 'section-heading' ||
+        f.type === 'html-block'
+      )
+        continue
+      if (!isFieldVisible(f, values as FormValues)) continue
+      out[f.id] = (values as FormValues)[f.id]
+    }
+    return out
+  }
+
+  return {
+    values: values as FormValues,
+    errors,
+    touched,
+    submitting,
+    submitted,
+    submitError,
+    fields,
+    steps,
+    currentStepIndex,
+    currentStep,
+    currentStepFields,
+    isFirstStep,
+    isLastStep,
+    visibleFields,
+    setValue,
+    touch,
+    validateCurrentScope,
+    validateAll,
+    next,
+    prev,
+    reset,
+    collectSubmissionValues,
+  }
+}

package/src/composables/useFormSubmission.ts

@@ -0,0 +1,113 @@
+import type {
+  DcsFormSubmitPayload,
+  DcsFormSubmitSuccess,
+  DcsFormSubmitError,
+} from '../types'
+
+export interface SubmitOptions {
+  apiBase: string
+  siteSlug: string
+  payload: DcsFormSubmitPayload
+  /** Number of retries on 5xx / network errors. Default 1. */
+  retries?: number
+  /** Optional fetch implementation override (tests). */
+  fetchImpl?: typeof fetch
+}
+
+/**
+ * POSTs a form submission to
+ * `${apiBase}/public/sites/{siteSlug}/form-submissions`.
+ *
+ * Uses JSON for plain values and `multipart/form-data` when any
+ * value is a `File` (file-upload fields).
+ */
+export async function submitFormValues(
+  opts: SubmitOptions,
+): Promise<DcsFormSubmitSuccess> {
+  const { apiBase, siteSlug, payload } = opts
+  const retries = opts.retries ?? 1
+  const fetchImpl = opts.fetchImpl ?? fetch
+  const url = `${apiBase.replace(/\/$/, '')}/public/sites/${encodeURIComponent(
+    siteSlug,
+  )}/form-submissions`
+
+  const hasFile = Object.values(payload.values).some(
+    (v) => typeof File !== 'undefined' && v instanceof File,
+  )
+
+  let lastError: Error | undefined
+  let lastStatus: number | undefined
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    try {
+      const init: RequestInit = hasFile
+        ? { method: 'POST', body: buildFormData(payload) }
+        : {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(payload),
+          }
+      const res = await fetchImpl(url, init)
+      lastStatus = res.status
+      if (res.ok) {
+        const body = await safeJson(res)
+        return { payload, response: body }
+      }
+      // Retry only on 5xx
+      if (res.status < 500) {
+        const body = await safeText(res)
+        const err: DcsFormSubmitError = {
+          payload,
+          status: res.status,
+          error: new Error(`Submission failed (${res.status}): ${body}`),
+        }
+        throw err
+      }
+      lastError = new Error(`Server error ${res.status}`)
+    } catch (e) {
+      // If `e` is already a DcsFormSubmitError-shaped object, rethrow.
+      if (e && typeof e === 'object' && 'payload' in e && 'error' in e) {
+        throw e
+      }
+      lastError = e as Error
+    }
+  }
+
+  throw {
+    payload,
+    status: lastStatus,
+    error: lastError ?? new Error('Submission failed'),
+  } satisfies DcsFormSubmitError
+}
+
+function buildFormData(payload: DcsFormSubmitPayload): FormData {
+  const fd = new FormData()
+  fd.append('formId', payload.formId)
+  if (payload.captchaToken) fd.append('captchaToken', payload.captchaToken)
+  for (const [key, value] of Object.entries(payload.values)) {
+    if (value === undefined || value === null) continue
+    if (value instanceof File) {
+      fd.append(`values[${key}]`, value)
+    } else if (Array.isArray(value)) {
+      for (const item of value) fd.append(`values[${key}][]`, String(item))
+    } else {
+      fd.append(`values[${key}]`, String(value))
+    }
+  }
+  return fd
+}
+
+async function safeJson(res: Response): Promise<unknown> {
+  try {
+    return await res.json()
+  } catch {
+    return null
+  }
+}
+
+async function safeText(res: Response): Promise<string> {
+  try {
+    return await res.text()
+  } catch {
+    return ''
+  }
+}

package/src/composables/useFormValidation.ts

@@ -0,0 +1,127 @@
+import type {
+  PortalFormDefinition,
+  PortalFormField,
+  FormErrors,
+  FormValues,
+} from '../types'
+
+/**
+ * Returns true iff `field` is currently visible given the form's
+ * other values. Hidden fields are never validated and never sent.
+ */
+export function isFieldVisible(
+  field: PortalFormField,
+  values: FormValues,
+): boolean {
+  if (!field.visibleIf) return true
+  const sibling = values[field.visibleIf.fieldId]
+  return sibling === field.visibleIf.equals
+}
+
+/**
+ * Validates a single field's value. Returns an error string or
+ * `undefined` if valid. Layout-only field types (section-heading,
+ * html-block) and hidden fields never produce errors.
+ */
+export function validateField(
+  field: PortalFormField,
+  value: unknown,
+): string | undefined {
+  if (
+    field.type === 'section-heading' ||
+    field.type === 'html-block' ||
+    field.type === 'hidden'
+  ) {
+    return undefined
+  }
+
+  const isEmpty =
+    value === undefined ||
+    value === null ||
+    value === '' ||
+    (Array.isArray(value) && value.length === 0)
+
+  if (field.required && isEmpty) {
+    return `${field.label} is required`
+  }
+  if (isEmpty) return undefined
+
+  // Type-specific built-ins
+  if (field.type === 'email' && typeof value === 'string') {
+    if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)) {
+      return `${field.label} must be a valid email address`
+    }
+  }
+
+  const v = field.validation
+  if (!v) return undefined
+
+  if (typeof value === 'string') {
+    if (v.minLength != null && value.length < v.minLength) {
+      return `${field.label} must be at least ${v.minLength} characters`
+    }
+    if (v.maxLength != null && value.length > v.maxLength) {
+      return `${field.label} must be at most ${v.maxLength} characters`
+    }
+    if (v.regex) {
+      try {
+        if (!new RegExp(v.regex).test(value)) {
+          return `${field.label} is invalid`
+        }
+      } catch {
+        // bad regex in the definition — treat as no rule
+      }
+    }
+  }
+
+  if (typeof value === 'number') {
+    if (v.min != null && value < v.min) {
+      return `${field.label} must be at least ${v.min}`
+    }
+    if (v.max != null && value > v.max) {
+      return `${field.label} must be at most ${v.max}`
+    }
+  }
+
+  if (field.type === 'file' && v.accept && v.accept.length > 0) {
+    const file = value as File | null
+    if (file && typeof File !== 'undefined' && file instanceof File) {
+      const accepted = v.accept.some((a) => {
+        if (a.startsWith('.')) {
+          return file.name.toLowerCase().endsWith(a.toLowerCase())
+        }
+        return file.type === a
+      })
+      if (!accepted) {
+        return `${field.label} must be one of: ${v.accept.join(', ')}`
+      }
+    }
+  }
+
+  return undefined
+}
+
+/**
+ * Validates an entire form. Skips fields that are not visible.
+ * If `fieldIds` is supplied, only those fields are validated
+ * (used for per-step validation in multi-step forms).
+ */
+export function validateForm(
+  def: PortalFormDefinition,
+  values: FormValues,
+  fieldIds?: string[],
+): FormErrors {
+  const errors: FormErrors = {}
+  const ids = fieldIds ? new Set(fieldIds) : null
+  for (const field of def.fields) {
+    if (ids && !ids.has(field.id)) continue
+    if (!isFieldVisible(field, values)) continue
+    const err = validateField(field, values[field.id])
+    if (err) errors[field.id] = err
+  }
+  return errors
+}
+
+export function hasErrors(errors: FormErrors): boolean {
+  return Object.values(errors).some((e) => !!e)
+}

package/src/fields/DcsFormCheckbox.vue

@@ -0,0 +1,35 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import type { PortalFormField } from '../types'
+import DcsFormFieldWrapper from './DcsFormFieldWrapper.vue'
+
+const props = defineProps<{
+  field: PortalFormField
+  modelValue: boolean | undefined
+  error?: string
+}>()
+
+const emit = defineEmits<{
+  'update:modelValue': [value: boolean]
+}>()
+
+const inputId = computed(() => `field-${props.field.id}`)
+</script>
+
+<template>
+  <DcsFormFieldWrapper :field="field" :error="error" :input-id="inputId">
+    <template #label><span class="sr-only">{{ field.label }}</span></template>
+    <label class="dcs-form-checkbox-single" :for="inputId">
+      <input
+        :id="inputId"
+        type="checkbox"
+        :name="field.id"
+        :checked="!!modelValue"
+        :required="field.required"
+        :aria-invalid="!!error"
+        @change="emit('update:modelValue', ($event.target as HTMLInputElement).checked)"
+      />
+      <span>{{ field.label }}<span v-if="field.required" aria-hidden="true"> *</span></span>
+    </label>
+  </DcsFormFieldWrapper>
+</template>

package/src/fields/DcsFormCheckboxGroup.vue

@@ -0,0 +1,52 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import type { PortalFormField } from '../types'
+import DcsFormFieldWrapper from './DcsFormFieldWrapper.vue'
+
+const props = defineProps<{
+  field: PortalFormField
+  modelValue: string[] | undefined
+  error?: string
+}>()
+
+const emit = defineEmits<{
+  'update:modelValue': [value: string[]]
+}>()
+
+const inputId = computed(() => `field-${props.field.id}`)
+const options = computed(() => props.field.options ?? [])
+const current = computed(() => props.modelValue ?? [])
+
+function toggle(value: string, checked: boolean): void {
+  const set = new Set(current.value)
+  if (checked) set.add(value)
+  else set.delete(value)
+  emit('update:modelValue', Array.from(set))
+}
+</script>
+
+<template>
+  <DcsFormFieldWrapper :field="field" :error="error" :input-id="inputId">
+    <fieldset
+      class="dcs-form-checkbox-group"
+      :aria-required="field.required"
+      :aria-invalid="!!error"
+    >
+      <legend class="sr-only">{{ field.label }}</legend>
+      <label
+        v-for="opt in options"
+        :key="opt.value"
+        class="dcs-form-checkbox"
+      >
+        <input
+          type="checkbox"
+          :name="`${field.id}[]`"
+          :value="opt.value"
+          :checked="current.includes(opt.value)"
+          @change="toggle(opt.value, ($event.target as HTMLInputElement).checked)"
+        />
+        <span>{{ opt.label }}</span>
+      </label>
+    </fieldset>
+  </DcsFormFieldWrapper>
+</template>

package/src/fields/DcsFormDate.vue

@@ -0,0 +1,34 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import type { PortalFormField } from '../types'
+import DcsFormFieldWrapper from './DcsFormFieldWrapper.vue'
+
+const props = defineProps<{
+  field: PortalFormField
+  modelValue: string | undefined
+  error?: string
+}>()
+
+const emit = defineEmits<{
+  'update:modelValue': [value: string]
+  blur: []
+}>()
+
+const inputId = computed(() => `field-${props.field.id}`)
+</script>
+
+<template>
+  <DcsFormFieldWrapper :field="field" :error="error" :input-id="inputId">
+    <input
+      :id="inputId"
+      class="dcs-form-input dcs-form-date"
+      type="date"
+      :name="field.id"
+      :required="field.required"
+      :aria-invalid="!!error"
+      :value="modelValue ?? ''"
+      @input="emit('update:modelValue', ($event.target as HTMLInputElement).value)"
+      @blur="emit('blur')"
+    />
+  </DcsFormFieldWrapper>
+</template>

package/src/fields/DcsFormFieldWrapper.vue

@@ -0,0 +1,39 @@
+<script setup lang="ts">
+import type { PortalFormField } from '../types'
+
+defineProps<{
+  field: PortalFormField
+  error?: string
+  /** Optional id to use for the input — wrappers use it for label `for=`. */
+  inputId?: string
+}>()
+</script>
+
+<template>
+  <div
+    class="dcs-form-field"
+    :class="[`dcs-form-field--${field.type}`, `dcs-form-field--width-${field.width ?? 'full'}`]"
+    :data-form-field-key="field.id"
+  >
+    <slot name="label">
+      <label
+        v-if="field.type !== 'checkbox' && field.type !== 'hidden' && field.type !== 'section-heading' && field.type !== 'html-block'"
+        :for="inputId ?? `field-${field.id}`"
+        class="dcs-form-field__label"
+      >
+        {{ field.label }}
+        <span v-if="field.required" aria-hidden="true" class="dcs-form-field__required">*</span>
+      </label>
+    </slot>
+
+    <slot />
+
+    <slot name="help">
+      <p v-if="field.helpText" class="dcs-form-field__help">{{ field.helpText }}</p>
+    </slot>
+
+    <slot name="error">
+      <p v-if="error" class="dcs-form-field__error" role="alert">{{ error }}</p>
+    </slot>
+  </div>
+</template>

package/src/fields/DcsFormFile.vue

@@ -0,0 +1,38 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import type { PortalFormField } from '../types'
+import DcsFormFieldWrapper from './DcsFormFieldWrapper.vue'
+
+const props = defineProps<{
+  field: PortalFormField
+  modelValue: File | undefined
+  error?: string
+}>()
+
+const emit = defineEmits<{
+  'update:modelValue': [value: File | undefined]
+}>()
+
+const inputId = computed(() => `field-${props.field.id}`)
+const accept = computed(() => (props.field.validation?.accept ?? []).join(','))
+
+function onChange(e: Event): void {
+  const target = e.target as HTMLInputElement
+  emit('update:modelValue', target.files?.[0])
+}
+</script>
+
+<template>
+  <DcsFormFieldWrapper :field="field" :error="error" :input-id="inputId">
+    <input
+      :id="inputId"
+      class="dcs-form-input dcs-form-file"
+      type="file"
+      :name="field.id"
+      :required="field.required"
+      :aria-invalid="!!error"
+      :accept="accept || undefined"
+      @change="onChange"
+    />
+  </DcsFormFieldWrapper>
+</template>

package/src/fields/DcsFormHidden.vue

@@ -0,0 +1,17 @@
+<script setup lang="ts">
+import type { PortalFormField } from '../types'
+
+defineProps<{
+  field: PortalFormField
+  modelValue: string | number | undefined
+}>()
+</script>
+
+<template>
+  <input
+    type="hidden"
+    :name="field.id"
+    :value="modelValue ?? (field.defaultValue as string | number | undefined) ?? ''"
+    :data-form-field-key="field.id"
+  />
+</template>

package/src/fields/DcsFormHtmlBlock.vue

@@ -0,0 +1,19 @@
+<script setup lang="ts">
+import type { PortalFormField } from '../types'
+
+defineProps<{
+  field: PortalFormField
+}>()
+</script>
+
+<template>
+  <!--
+    `html` is sanitized server-side per the schema; rendering with v-html
+    is intentional. Site authors must keep portal-side sanitization on.
+  -->
+  <div
+    class="dcs-form-html-block"
+    :data-form-field-key="field.id"
+    v-html="field.html ?? ''"
+  />
+</template>