@duffcloudservices/site-forms 0.1.0

package/src/DcsForm.vue

@@ -0,0 +1,299 @@
+<script setup lang="ts">
+import { computed, onMounted, ref, watch } from 'vue'
+import type {
+  DcsFormSubmitError,
+  DcsFormSubmitSuccess,
+  PortalFormDefinition,
+  PortalFormField,
+} from './types'
+import { useDcsForm } from './composables/useDcsForm'
+import { submitFormValues } from './composables/useFormSubmission'
+import { warnIfInvalid } from './schema/validate'
+import { loadFormDefinitions } from './loaders/yaml'
+
+import DcsFormText from './fields/DcsFormText.vue'
+import DcsFormTextarea from './fields/DcsFormTextarea.vue'
+import DcsFormSelect from './fields/DcsFormSelect.vue'
+import DcsFormRadio from './fields/DcsFormRadio.vue'
+import DcsFormCheckboxGroup from './fields/DcsFormCheckboxGroup.vue'
+import DcsFormCheckbox from './fields/DcsFormCheckbox.vue'
+import DcsFormDate from './fields/DcsFormDate.vue'
+import DcsFormFile from './fields/DcsFormFile.vue'
+import DcsFormHidden from './fields/DcsFormHidden.vue'
+import DcsFormSection from './fields/DcsFormSection.vue'
+import DcsFormHtmlBlock from './fields/DcsFormHtmlBlock.vue'
+
+interface Props {
+  /** Kebab-case form id; matches `.dcs/forms/<formId>.yaml`. */
+  formId: string
+  /** Site slug used for the submission endpoint path. */
+  siteSlug?: string
+  /** Override the loaded definition (used by the portal preview iframe). */
+  definitionOverride?: PortalFormDefinition
+  /** Override the API base URL; defaults to `VITE_DCS_PUBLIC_API`. */
+  apiBase?: string
+  /** Optional captcha token, attached to the submission payload. */
+  captchaToken?: string
+  /**
+   * Optional override for the YAML modules map. Mostly for tests; in
+   * real apps the build-time `import.meta.glob` call below is used.
+   */
+  formsModules?: Record<string, unknown>
+}
+
+const props = defineProps<Props>()
+
+const emit = defineEmits<{
+  'submit-success': [event: DcsFormSubmitSuccess]
+  'submit-error': [event: DcsFormSubmitError]
+  'validation-error': [errors: Record<string, string | undefined>]
+}>()
+
+// Eager glob — Vite inlines every site form at build time. Customer
+// sites should configure `vite-plugin-yaml` so YAML is parsed to an
+// object; without it the loader falls back to parsing raw strings.
+const eagerFormsModules = (import.meta as unknown as {
+  glob: (
+    pattern: string,
+    opts: { eager: true; import: string; query?: string },
+  ) => Record<string, unknown>
+}).glob('/.dcs/forms/*.yaml', { eager: true, import: 'default' })
+
+const definitions = computed(() =>
+  loadFormDefinitions(props.formsModules ?? eagerFormsModules),
+)
+
+const definition = computed<PortalFormDefinition | null>(() => {
+  if (props.definitionOverride) return props.definitionOverride
+  return definitions.value[props.formId] ?? null
+})
+
+const isDev = !!(import.meta as unknown as { env?: { DEV?: boolean } }).env?.DEV
+
+watch(
+  definition,
+  (def) => {
+    if (def) warnIfInvalid(props.formId, def, isDev)
+  },
+  { immediate: true },
+)
+
+// We always call useDcsForm with *some* definition so hooks render
+// stably; if the form is missing we'll show an error state instead.
+const safeDefinition = computed<PortalFormDefinition>(
+  () =>
+    definition.value ?? {
+      formId: props.formId,
+      title: '',
+      submission: { kind: 'lead' },
+      fields: [],
+    },
+)
+
+const form = useDcsForm({ definition: safeDefinition.value })
+
+// If the resolved definition changes (e.g. preview iframe updates),
+// re-create derived state by resetting.
+watch(
+  () => safeDefinition.value,
+  () => form.reset(),
+)
+
+const apiBase = computed(
+  () =>
+    props.apiBase ??
+    (import.meta as unknown as { env?: { VITE_DCS_PUBLIC_API?: string } }).env
+      ?.VITE_DCS_PUBLIC_API ??
+    '',
+)
+
+const resolvedSiteSlug = computed(
+  () =>
+    props.siteSlug ??
+    (import.meta as unknown as { env?: { VITE_DCS_SITE_SLUG?: string } }).env
+      ?.VITE_DCS_SITE_SLUG ??
+    '',
+)
+
+const submitLabel = computed(
+  () => safeDefinition.value.submitLabel ?? 'Send',
+)
+
+function fieldComponent(field: PortalFormField) {
+  switch (field.type) {
+    case 'text':
+    case 'email':
+    case 'tel':
+      return DcsFormText
+    case 'textarea':
+      return DcsFormTextarea
+    case 'select':
+    case 'multiselect':
+      return DcsFormSelect
+    case 'radio':
+      return DcsFormRadio
+    case 'checkbox-group':
+      return DcsFormCheckboxGroup
+    case 'checkbox':
+      return DcsFormCheckbox
+    case 'date':
+      return DcsFormDate
+    case 'file':
+      return DcsFormFile
+    case 'hidden':
+      return DcsFormHidden
+    case 'section-heading':
+      return DcsFormSection
+    case 'html-block':
+      return DcsFormHtmlBlock
+    default:
+      return DcsFormText
+  }
+}
+
+const formEl = ref<HTMLFormElement | null>(null)
+
+async function onSubmit(e: Event): Promise<void> {
+  e.preventDefault()
+  if (!definition.value) return
+  const ok = form.validateAll()
+  if (!ok) {
+    emit('validation-error', form.errors.value)
+    return
+  }
+  form.submitting.value = true
+  form.submitError.value = null
+  const payload = {
+    formId: props.formId,
+    values: form.collectSubmissionValues(),
+    captchaToken: props.captchaToken,
+  }
+  try {
+    const result = await submitFormValues({
+      apiBase: apiBase.value,
+      siteSlug: resolvedSiteSlug.value,
+      payload,
+    })
+    form.submitted.value = true
+    emit('submit-success', result)
+  } catch (err) {
+    const e2 = err as DcsFormSubmitError
+    form.submitError.value = e2.error?.message ?? 'Submission failed'
+    emit('submit-error', e2)
+  } finally {
+    form.submitting.value = false
+  }
+}
+
+onMounted(() => {
+  if (!definition.value) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[@duffcloudservices/site-forms] No form definition found for "${props.formId}". ` +
+        `Expected a YAML at /.dcs/forms/${props.formId}.yaml.`,
+    )
+  }
+})
+</script>
+
+<template>
+  <div v-if="!definition" class="dcs-form dcs-form--missing" :data-form-key="formId">
+    <slot name="missing" :form-id="formId">
+      <p>Form &ldquo;{{ formId }}&rdquo; is not configured.</p>
+    </slot>
+  </div>
+
+  <div v-else-if="form.submitted.value" class="dcs-form dcs-form--success" :data-form-key="formId">
+    <slot name="success" :definition="definition">
+      <p>{{ definition.successMessage ?? 'Thanks — we received your message.' }}</p>
+    </slot>
+  </div>
+
+  <form
+    v-else
+    ref="formEl"
+    class="dcs-form"
+    :data-form-key="formId"
+    novalidate
+    @submit="onSubmit"
+  >
+    <slot name="header" :definition="definition">
+      <header class="dcs-form__header">
+        <h2 class="dcs-form__title">{{ definition.title }}</h2>
+        <p v-if="definition.description" class="dcs-form__description">
+          {{ definition.description }}
+        </p>
+      </header>
+    </slot>
+
+    <div v-if="form.steps.value" class="dcs-form__progress" aria-live="polite">
+      <slot
+        name="progress"
+        :current="form.currentStepIndex.value"
+        :total="form.steps.value.length"
+        :step="form.currentStep.value"
+      >
+        <p>
+          Step {{ form.currentStepIndex.value + 1 }} of
+          {{ form.steps.value.length }}
+          <template v-if="form.currentStep.value">
+            — {{ form.currentStep.value.title }}
+          </template>
+        </p>
+      </slot>
+    </div>
+
+    <div class="dcs-form__fields">
+      <component
+        :is="fieldComponent(field)"
+        v-for="field in form.visibleFields.value"
+        :key="field.id"
+        :field="field"
+        :model-value="form.values[field.id]"
+        :error="form.errors.value[field.id]"
+        @update:model-value="(v: unknown) => form.setValue(field.id, v)"
+        @blur="form.touch(field.id)"
+      />
+    </div>
+
+    <div v-if="form.submitError.value" class="dcs-form__submit-error" role="alert">
+      {{ form.submitError.value }}
+    </div>
+
+    <div class="dcs-form__actions">
+      <slot
+        name="actions"
+        :is-first-step="form.isFirstStep.value"
+        :is-last-step="form.isLastStep.value"
+        :submitting="form.submitting.value"
+        :prev="form.prev"
+        :next="form.next"
+      >
+        <button
+          v-if="form.steps.value && !form.isFirstStep.value"
+          type="button"
+          class="dcs-form__btn dcs-form__btn--prev"
+          @click="form.prev()"
+        >
+          Previous
+        </button>
+        <button
+          v-if="form.steps.value && !form.isLastStep.value"
+          type="button"
+          class="dcs-form__btn dcs-form__btn--next"
+          @click="form.next()"
+        >
+          Next
+        </button>
+        <button
+          v-if="!form.steps.value || form.isLastStep.value"
+          type="submit"
+          class="dcs-form__btn dcs-form__btn--submit"
+          :disabled="form.submitting.value"
+        >
+          {{ form.submitting.value ? 'Sending…' : submitLabel }}
+        </button>
+      </slot>
+    </div>
+  </form>
+</template>

package/src/__tests__/fields.test.ts

@@ -0,0 +1,82 @@
+import { describe, it, expect } from 'vitest'
+import { mount } from '@vue/test-utils'
+import DcsForm from '../DcsForm.vue'
+import type { PortalFormDefinition } from '../types'
+
+function makeDef(
+  overrides: Partial<PortalFormDefinition> = {},
+): PortalFormDefinition {
+  return {
+    formId: 'contact',
+    title: 'Contact',
+    submission: { kind: 'lead' },
+    fields: [
+      { id: 'name', type: 'text', label: 'Name', required: true },
+      { id: 'email', type: 'email', label: 'Email', required: true },
+      { id: 'message', type: 'textarea', label: 'Message' },
+    ],
+    ...overrides,
+  }
+}
+
+describe('field rendering', () => {
+  it('emits data-form-key on the form element', () => {
+    const wrapper = mount(DcsForm, {
+      props: { formId: 'contact', siteSlug: 's', definitionOverride: makeDef() },
+    })
+    const form = wrapper.find('form')
+    expect(form.attributes('data-form-key')).toBe('contact')
+  })
+
+  it('renders an input per text field with data-form-field-key', () => {
+    const wrapper = mount(DcsForm, {
+      props: { formId: 'contact', siteSlug: 's', definitionOverride: makeDef() },
+    })
+    expect(wrapper.find('[data-form-field-key="name"] input[type="text"]').exists()).toBe(true)
+    expect(wrapper.find('[data-form-field-key="email"] input[type="email"]').exists()).toBe(true)
+    expect(wrapper.find('[data-form-field-key="message"] textarea').exists()).toBe(true)
+  })
+
+  it('renders select / radio / checkbox-group / date / file / hidden / section / html-block', () => {
+    const def = makeDef({
+      fields: [
+        {
+          id: 'sel',
+          type: 'select',
+          label: 'Sel',
+          options: [{ value: 'a', label: 'A' }],
+        },
+        {
+          id: 'rad',
+          type: 'radio',
+          label: 'Rad',
+          options: [{ value: 'a', label: 'A' }],
+        },
+        {
+          id: 'chg',
+          type: 'checkbox-group',
+          label: 'Chg',
+          options: [{ value: 'a', label: 'A' }],
+        },
+        { id: 'cb', type: 'checkbox', label: 'CB' },
+        { id: 'dt', type: 'date', label: 'Dt' },
+        { id: 'f', type: 'file', label: 'F' },
+        { id: 'h', type: 'hidden', label: 'H', defaultValue: 'x' },
+        { id: 'sec', type: 'section-heading', label: 'Sec' },
+        { id: 'html', type: 'html-block', label: 'HTML', html: '<p>hi</p>' },
+      ],
+    })
+    const wrapper = mount(DcsForm, {
+      props: { formId: 'contact', siteSlug: 's', definitionOverride: def },
+    })
+    expect(wrapper.find('[data-form-field-key="sel"] select').exists()).toBe(true)
+    expect(wrapper.find('[data-form-field-key="rad"] input[type="radio"]').exists()).toBe(true)
+    expect(wrapper.find('[data-form-field-key="chg"] input[type="checkbox"]').exists()).toBe(true)
+    expect(wrapper.find('[data-form-field-key="cb"] input[type="checkbox"]').exists()).toBe(true)
+    expect(wrapper.find('[data-form-field-key="dt"] input[type="date"]').exists()).toBe(true)
+    expect(wrapper.find('[data-form-field-key="f"] input[type="file"]').exists()).toBe(true)
+    expect(wrapper.find('input[type="hidden"][name="h"]').exists()).toBe(true)
+    expect(wrapper.find('[data-form-field-key="sec"] h3').exists()).toBe(true)
+    expect(wrapper.find('[data-form-field-key="html"]').html()).toContain('<p>hi</p>')
+  })
+})

package/src/__tests__/multi-step.test.ts

@@ -0,0 +1,46 @@
+import { describe, it, expect } from 'vitest'
+import { mount, flushPromises } from '@vue/test-utils'
+import DcsForm from '../DcsForm.vue'
+import type { PortalFormDefinition } from '../types'
+
+const def: PortalFormDefinition = {
+  formId: 'wiz',
+  title: 'Wizard',
+  submission: { kind: 'lead' },
+  steps: [
+    { id: 's1', title: 'One', fieldIds: ['a'] },
+    { id: 's2', title: 'Two', fieldIds: ['b'] },
+  ],
+  fields: [
+    { id: 'a', type: 'text', label: 'A', required: true },
+    { id: 'b', type: 'text', label: 'B', required: true },
+  ],
+}
+
+describe('multi-step navigation', () => {
+  it('starts on step 1, blocks Next until current step is valid', async () => {
+    const wrapper = mount(DcsForm, {
+      props: { formId: 'wiz', siteSlug: 's', definitionOverride: def },
+    })
+    expect(wrapper.text()).toContain('Step 1 of 2')
+    // Step 1 field B is not visible yet
+    expect(wrapper.find('[data-form-field-key="a"]').exists()).toBe(true)
+    expect(wrapper.find('[data-form-field-key="b"]').exists()).toBe(false)
+
+    // Click Next without filling A — should not advance
+    await wrapper.find('.dcs-form__btn--next').trigger('click')
+    expect(wrapper.text()).toContain('Step 1 of 2')
+    expect(wrapper.text()).toContain('A is required')
+
+    // Fill A, then advance
+    await wrapper.find('[data-form-field-key="a"] input').setValue('hi')
+    await wrapper.find('.dcs-form__btn--next').trigger('click')
+    await flushPromises()
+    expect(wrapper.text()).toContain('Step 2 of 2')
+    expect(wrapper.find('[data-form-field-key="b"]').exists()).toBe(true)
+
+    // Prev returns
+    await wrapper.find('.dcs-form__btn--prev').trigger('click')
+    expect(wrapper.text()).toContain('Step 1 of 2')
+  })
+})

package/src/__tests__/schema.test.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect, vi } from 'vitest'
+import { validateFormDefinition, warnIfInvalid } from '../schema/validate'
+import type { PortalFormDefinition } from '../types'
+
+const valid: PortalFormDefinition = {
+  formId: 'contact',
+  title: 'Contact',
+  submission: { kind: 'lead' },
+  fields: [
+    { id: 'name', type: 'text', label: 'Name', required: true },
+    { id: 'email', type: 'email', label: 'Email', required: true },
+  ],
+}
+
+describe('schema validate', () => {
+  it('passes for a well-formed definition', () => {
+    const r = validateFormDefinition(valid)
+    expect(r.valid).toBe(true)
+    expect(r.errors).toEqual([])
+  })
+
+  it('fails when required keys are missing', () => {
+    const bad = { formId: 'x' } as unknown as PortalFormDefinition
+    const r = validateFormDefinition(bad)
+    expect(r.valid).toBe(false)
+    expect(r.errors.length).toBeGreaterThan(0)
+  })
+
+  it('emits a dev-only console.warn for malformed definitions', () => {
+    const spy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    warnIfInvalid('contact', { formId: 'contact' }, true)
+    expect(spy).toHaveBeenCalled()
+    spy.mockRestore()
+  })
+
+  it('does NOT warn when not in dev mode', () => {
+    const spy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    warnIfInvalid('contact', { formId: 'contact' }, false)
+    expect(spy).not.toHaveBeenCalled()
+    spy.mockRestore()
+  })
+})

package/src/__tests__/submission.test.ts

@@ -0,0 +1,77 @@
+import { describe, it, expect, vi } from 'vitest'
+import { mount, flushPromises } from '@vue/test-utils'
+import DcsForm from '../DcsForm.vue'
+import type { PortalFormDefinition } from '../types'
+
+const def: PortalFormDefinition = {
+  formId: 'contact',
+  title: 'Contact',
+  submission: { kind: 'lead' },
+  fields: [
+    { id: 'name', type: 'text', label: 'Name', required: true },
+    { id: 'email', type: 'email', label: 'Email', required: true },
+    { id: 'message', type: 'textarea', label: 'Message' },
+  ],
+}
+
+describe('submission happy path', () => {
+  it('POSTs the right payload shape and emits submit-success', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: async () => ({ leadId: 'L-1' }),
+    })
+    const originalFetch = globalThis.fetch
+    ;(globalThis as unknown as { fetch: typeof fetch }).fetch =
+      fetchMock as unknown as typeof fetch
+
+    const wrapper = mount(DcsForm, {
+      props: {
+        formId: 'contact',
+        siteSlug: 'kept',
+        definitionOverride: def,
+        apiBase: 'https://api.example.com/',
+        captchaToken: 'tok-abc',
+      },
+    })
+
+    await wrapper.find('[data-form-field-key="name"] input').setValue('Jane')
+    await wrapper.find('[data-form-field-key="email"] input').setValue('jane@example.com')
+    await wrapper.find('[data-form-field-key="message"] textarea').setValue('hello')
+
+    await wrapper.find('form').trigger('submit')
+    await flushPromises()
+
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+    const [url, init] = fetchMock.mock.calls[0]
+    expect(url).toBe('https://api.example.com/public/sites/kept/form-submissions')
+    expect((init as RequestInit).method).toBe('POST')
+    expect(((init as RequestInit).headers as Record<string, string>)['Content-Type']).toBe(
+      'application/json',
+    )
+    const body = JSON.parse((init as RequestInit).body as string)
+    expect(body).toEqual({
+      formId: 'contact',
+      values: { name: 'Jane', email: 'jane@example.com', message: 'hello' },
+      captchaToken: 'tok-abc',
+    })
+
+    expect(wrapper.emitted('submit-success')?.length).toBe(1)
+
+    ;(globalThis as unknown as { fetch: typeof fetch }).fetch = originalFetch
+  })
+
+  it('emits validation-error when required fields are missing', async () => {
+    const wrapper = mount(DcsForm, {
+      props: {
+        formId: 'contact',
+        siteSlug: 'kept',
+        definitionOverride: def,
+        apiBase: 'https://api.example.com',
+      },
+    })
+    await wrapper.find('form').trigger('submit')
+    await flushPromises()
+    expect(wrapper.emitted('validation-error')?.length).toBe(1)
+  })
+})

package/src/__tests__/visible-if.test.ts

@@ -0,0 +1,111 @@
+import { describe, it, expect, vi } from 'vitest'
+import { mount, flushPromises } from '@vue/test-utils'
+import DcsForm from '../DcsForm.vue'
+import type { PortalFormDefinition } from '../types'
+
+const def: PortalFormDefinition = {
+  formId: 'gated',
+  title: 'Gated',
+  submission: { kind: 'lead' },
+  fields: [
+    {
+      id: 'kind',
+      type: 'radio',
+      label: 'Kind',
+      required: true,
+      options: [
+        { value: 'a', label: 'A' },
+        { value: 'b', label: 'B' },
+      ],
+    },
+    {
+      id: 'detail',
+      type: 'text',
+      label: 'Detail',
+      required: true,
+      visibleIf: { fieldId: 'kind', equals: 'b' },
+    },
+  ],
+}
+
+describe('visibleIf', () => {
+  it('skips validation and submission for hidden gated fields', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: async () => ({ id: '1' }),
+    })
+    // Stub global fetch
+    const originalFetch = globalThis.fetch
+    ;(globalThis as unknown as { fetch: typeof fetch }).fetch =
+      fetchMock as unknown as typeof fetch
+
+    const wrapper = mount(DcsForm, {
+      props: {
+        formId: 'gated',
+        siteSlug: 'site-x',
+        definitionOverride: def,
+        apiBase: 'https://api.test',
+      },
+    })
+
+    // detail field is hidden initially
+    expect(wrapper.find('[data-form-field-key="detail"]').exists()).toBe(false)
+
+    // Choose kind=a (does not reveal detail)
+    await wrapper.find('input[type="radio"][value="a"]').setChecked(true)
+    await wrapper.find('form').trigger('submit')
+    await flushPromises()
+
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+    const [, init] = fetchMock.mock.calls[0]
+    const body = JSON.parse((init as RequestInit).body as string)
+    expect(body.values).toEqual({ kind: 'a' })
+    expect('detail' in body.values).toBe(false)
+
+    ;(globalThis as unknown as { fetch: typeof fetch }).fetch = originalFetch
+  })
+
+  it('validates and submits the gated field once visible', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: async () => ({}),
+    })
+    const originalFetch = globalThis.fetch
+    ;(globalThis as unknown as { fetch: typeof fetch }).fetch =
+      fetchMock as unknown as typeof fetch
+
+    const wrapper = mount(DcsForm, {
+      props: {
+        formId: 'gated',
+        siteSlug: 'site-x',
+        definitionOverride: def,
+        apiBase: 'https://api.test',
+      },
+    })
+    await wrapper.find('input[type="radio"][value="b"]').setChecked(true)
+    // detail should now be visible and required
+    expect(wrapper.find('[data-form-field-key="detail"]').exists()).toBe(true)
+
+    await wrapper.find('form').trigger('submit')
+    await flushPromises()
+    expect(fetchMock).not.toHaveBeenCalled()
+    expect(wrapper.text()).toContain('Detail is required')
+
+    await wrapper.find('[data-form-field-key="detail"] input').setValue('xyz')
+    await wrapper.find('form').trigger('submit')
+    await flushPromises()
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+    const [url, init] = fetchMock.mock.calls[0]
+    expect(url).toBe('https://api.test/public/sites/site-x/form-submissions')
+    const body = JSON.parse((init as RequestInit).body as string)
+    expect(body).toEqual({
+      formId: 'gated',
+      values: { kind: 'b', detail: 'xyz' },
+      captchaToken: undefined,
+    })
+
+    ;(globalThis as unknown as { fetch: typeof fetch }).fetch = originalFetch
+  })
+})