@asd20/ui-next 2.23.6 → 2.24.1

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [2.24.1](https://github.com/academydistrict20/asd20-ui-next/compare/ui-next-v2.24.0...ui-next-v2.24.1) (2026-09-16)
+
+
+### Bug Fixes
+
+* restore public form modal styling ([2119cb9](https://github.com/academydistrict20/asd20-ui-next/commit/2119cb936bf03911ce8c83f9adbbcefc81b6cb3a))
+
+# [2.24.0](https://github.com/academydistrict20/asd20-ui-next/compare/ui-next-v2.23.6...ui-next-v2.24.0) (2026-09-16)
+
+
+### Features
+
+* add generic public form components ([12e7f88](https://github.com/academydistrict20/asd20-ui-next/commit/12e7f8812980744c46786b9effefe4cc15b5420a))
+
 ## [2.23.6](https://github.com/academydistrict20/asd20-ui-next/compare/ui-next-v2.23.5...ui-next-v2.23.6) (2026-09-16)
 
 

package/components.js

@@ -50,6 +50,7 @@ export { default as Asd20Modal } from './src/components/molecules/Asd20Modal/ind
 export { default as Asd20Notification } from './src/components/molecules/Asd20Notification/index.vue'
 export { default as Asd20Picker } from './src/components/molecules/Asd20Picker/index.vue'
 export { default as Asd20Progress } from './src/components/molecules/Asd20Progress/index.vue'
+export { default as Asd20PublicFormField } from './src/components/molecules/Asd20PublicFormField/index.vue'
 export { default as Asd20SearchField } from './src/components/molecules/Asd20SearchField/index.vue'
 export { default as Asd20Share } from './src/components/molecules/Asd20Share/index.vue'
 export { default as Asd20SliderInput } from './src/components/molecules/Asd20SliderInput/index.vue'
@@ -93,6 +94,7 @@ export { default as Asd20PageHeader } from './src/components/organisms/Asd20Page
 export { default as Asd20PeopleList } from './src/components/organisms/Asd20PeopleList/index.vue'
 export { default as Asd20PersonModal } from './src/components/organisms/Asd20PersonModal/index.vue'
 export { default as Asd20PrimaryHeader } from './src/components/organisms/Asd20PrimaryHeader/index.vue'
+export { default as Asd20PublicFormModal } from './src/components/organisms/Asd20PublicFormModal/index.vue'
 export { default as Asd20QuicklinksMenu } from './src/components/organisms/Asd20QuicklinksMenu/index.vue'
 export { default as Asd20SchoolHomepageHeader } from './src/components/organisms/Asd20SchoolHomepageHeader/index.vue'
 export { default as Asd20SchoolHomepageVideoHeader } from './src/components/organisms/Asd20SchoolHomepageVideoHeader/index.vue'

package/helpers.js

@@ -36,6 +36,13 @@ export { default as organizationItemsByCategory } from './src/helpers/organizati
 export { default as organizationSubtitle } from './src/helpers/organizationSubtitle.js'
 export { default as organizationTitle } from './src/helpers/organizationTitle.js'
 export { default as preventWidows } from './src/helpers/prevent-widows.js'
+export {
+  fetchPublicFormDefinition,
+  normalizeFormId,
+  resolvePublicFormEndpoints,
+  resolvePublicFormsEndpoint,
+  submitPublicForm,
+} from './src/helpers/publicForms.js'
 export { default as queryAiSite } from './src/helpers/queryAiSite.js'
 export { default as queryDepartments } from './src/helpers/queryDepartments.js'
 export { default as queryEvents } from './src/helpers/queryEvents.js'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asd20/ui-next",
-  "version": "2.23.6",
+  "version": "2.24.1",
   "private": false,
   "description": "ASD20 UI component library for Vue 3.",
   "license": "MIT",

package/src/components/molecules/Asd20PublicFormField/index.vue

@@ -0,0 +1,215 @@
+<template>
+  <div class="asd20-public-form-field">
+    <asd20-text-area-input
+      v-if="field.type === 'textarea'"
+      :id="inputId"
+      :model-value="modelValue"
+      :label="displayLabel"
+      :required="field.required"
+      :minlength="field.minLength"
+      :maxlength="field.maxLength"
+      :autocomplete="field.autocomplete || undefined"
+      :aria-describedby="describedBy"
+      :aria-invalid="hasErrors ? 'true' : undefined"
+      @update:modelValue="$emit('update:modelValue', $event)"
+    />
+
+    <asd20-text-input
+      v-else-if="textInputTypes.includes(field.type)"
+      :id="inputId"
+      :model-value="modelValue"
+      :label="displayLabel"
+      :type="field.type"
+      :required="field.required"
+      :minlength="field.minLength"
+      :maxlength="field.maxLength"
+      :autocomplete="field.autocomplete || undefined"
+      :aria-describedby="describedBy"
+      :aria-invalid="hasErrors ? 'true' : undefined"
+      @update:modelValue="$emit('update:modelValue', $event)"
+    />
+
+    <div
+      v-else-if="field.type === 'select'"
+      class="asd20-public-form-field__select"
+    >
+      <label :for="inputId">{{ displayLabel }}</label>
+      <select
+        :id="inputId"
+        :value="modelValue"
+        :required="field.required"
+        :aria-describedby="describedBy"
+        :aria-invalid="hasErrors ? 'true' : undefined"
+        @change="$emit('update:modelValue', $event.target.value)"
+      >
+        <option value="">
+          Please select
+        </option>
+        <option
+          v-for="option in field.options"
+          :key="option.value"
+          :value="option.value"
+        >
+          {{ option.label }}
+        </option>
+      </select>
+    </div>
+
+    <fieldset
+      v-else-if="field.type === 'radio'"
+      class="asd20-public-form-field__choices"
+      :aria-describedby="describedBy"
+      :aria-invalid="hasErrors ? 'true' : undefined"
+    >
+      <legend>{{ displayLabel }}</legend>
+      <label
+        v-for="option in field.options"
+        :key="option.value"
+        :for="`${inputId}-${option.value}`"
+      >
+        <input
+          :id="`${inputId}-${option.value}`"
+          :name="inputId"
+          type="radio"
+          :value="option.value"
+          :checked="modelValue === option.value"
+          :required="field.required"
+          @change="$emit('update:modelValue', option.value)"
+        />
+        <span>{{ option.label }}</span>
+      </label>
+    </fieldset>
+
+    <asd20-checkbox
+      v-else-if="field.type === 'checkbox'"
+      :id="inputId"
+      :model-value="modelValue === true"
+      :label="displayLabel"
+      checkbox
+      :required="field.required || undefined"
+      :aria-describedby="describedBy"
+      :aria-invalid="hasErrors ? 'true' : undefined"
+      @update:modelValue="$emit('update:modelValue', $event)"
+    />
+
+    <p
+      v-if="field.helpText"
+      :id="helpId"
+      class="asd20-public-form-field__help"
+    >
+      {{ field.helpText }}
+    </p>
+    <ul
+      v-if="hasErrors"
+      :id="errorId"
+      class="asd20-public-form-field__errors"
+    >
+      <li
+        v-for="error in errors"
+        :key="error"
+      >
+        {{ error }}
+      </li>
+    </ul>
+  </div>
+</template>
+
+<script>
+import Asd20Checkbox from '../../atoms/Asd20Checkbox'
+import Asd20TextAreaInput from '../Asd20TextAreaInput'
+import Asd20TextInput from '../Asd20TextInput'
+
+export default {
+  name: 'Asd20PublicFormField',
+  components: { Asd20Checkbox, Asd20TextAreaInput, Asd20TextInput },
+  props: {
+    field: { type: Object, required: true },
+    modelValue: { type: [String, Boolean], default: '' },
+    errors: { type: Array, default: () => [] },
+    inputId: { type: String, required: true },
+  },
+  emits: ['update:modelValue'],
+  data() {
+    return {
+      textInputTypes: ['text', 'email', 'tel', 'date'],
+    }
+  },
+  computed: {
+    displayLabel() {
+      return this.field.required
+        ? `${this.field.label} (required)`
+        : this.field.label
+    },
+    helpId() {
+      return `${this.inputId}-help`
+    },
+    errorId() {
+      return `${this.inputId}-error`
+    },
+    hasErrors() {
+      return this.errors.length > 0
+    },
+    describedBy() {
+      return (
+        [
+          this.field.helpText ? this.helpId : '',
+          this.hasErrors ? this.errorId : '',
+        ]
+          .filter(Boolean)
+          .join(' ') || undefined
+      )
+    },
+  },
+}
+</script>
+
+<style lang="scss" scoped>
+@use '../../../design/component-stack' as *;
+
+.asd20-public-form-field {
+  margin-bottom: space(0.5);
+
+  &__select label,
+  legend {
+    color: var(--website-card__reverse-background-color);
+    display: block;
+    margin-bottom: space(0.125);
+  }
+
+  select {
+    background: white;
+    border: 2px solid var(--color__accent);
+    border-radius: var(--website-shape__radius-s);
+    box-sizing: border-box;
+    color: var(--website-card__reverse-background-color);
+    font: inherit;
+    padding: space(0.25);
+    width: 100%;
+  }
+
+  fieldset {
+    border: 0;
+    margin: 0;
+    padding: 0;
+  }
+
+  &__choices label {
+    align-items: center;
+    display: flex;
+    gap: space(0.25);
+    margin: space(0.125) 0;
+  }
+
+  &__help,
+  &__errors {
+    color: var(--website-card__reverse-background-color);
+    font-size: 0.75rem;
+    margin: space(0.125) 0 0;
+  }
+
+  &__errors {
+    color: asd20-swatch('emergency', -1);
+    padding-left: space(1);
+  }
+}
+</style>

package/src/components/organisms/Asd20PublicFormModal/index.vue

@@ -0,0 +1,504 @@
+<template>
+  <asd20-modal
+    :open="open"
+    :title="modalTitle"
+    icon="contact"
+    dismissable
+    class="asd20-public-form-modal"
+    @dismiss="dismiss"
+  >
+    <asd20-viewport scrollable>
+      <div
+        v-if="loadingDefinition"
+        class="asd20-public-form-modal__state"
+        role="status"
+        aria-live="polite"
+      >
+        <asd20-spinner size="sm" />
+        <span>Loading form…</span>
+      </div>
+
+      <div
+        v-else-if="definitionError"
+        ref="definitionError"
+        class="asd20-public-form-modal__feedback"
+        role="alert"
+        tabindex="-1"
+      >
+        {{ definitionError }}
+      </div>
+
+      <div
+        v-else-if="submissionSuccess"
+        class="asd20-public-form-modal__success"
+        role="status"
+        aria-live="polite"
+      >
+        {{ formDefinition.successMessage }}
+      </div>
+
+      <form
+        v-else-if="formDefinition"
+        novalidate
+        @submit.prevent="validateBeforeCaptcha"
+      >
+        <p
+          v-if="formDefinition.introduction"
+          class="asd20-public-form-modal__introduction"
+        >
+          {{ formDefinition.introduction }}
+        </p>
+
+        <div
+          v-if="errorEntries.length"
+          ref="errorSummary"
+          class="asd20-public-form-modal__error-summary"
+          role="alert"
+          tabindex="-1"
+        >
+          <p>Please correct the following fields:</p>
+          <ul>
+            <li
+              v-for="entry in errorEntries"
+              :key="entry.name"
+            >
+              <a
+                :href="`#${fieldId(entry.name)}`"
+                @click.prevent="focusField(entry.name)"
+              >{{ entry.messages[0] }}</a>
+            </li>
+          </ul>
+        </div>
+
+        <asd20-public-form-field
+          v-for="field in formDefinition.fields"
+          :key="field.name"
+          :field="field"
+          :input-id="fieldId(field.name)"
+          :model-value="values[field.name]"
+          :errors="validationErrors[field.name] || []"
+          @update:modelValue="updateValue(field.name, $event)"
+        />
+
+        <div
+          class="asd20-public-form-modal__honeypot"
+          aria-hidden="true"
+        >
+          <label :for="honeypotId">Website</label>
+          <input
+            :id="honeypotId"
+            v-model="honeypot"
+            type="text"
+            name="website"
+            tabindex="-1"
+            autocomplete="off"
+          />
+        </div>
+
+        <div
+          v-if="hasFallbackContact"
+          class="asd20-public-form-modal__fallback"
+        >
+          <p>
+            If you cannot submit this form, use one of these contact options:
+          </p>
+          <a
+            v-if="formDefinition.fallbackContact.email"
+            :href="`mailto:${formDefinition.fallbackContact.email}`"
+          >{{ formDefinition.fallbackContact.email }}</a>
+          <a
+            v-if="formDefinition.fallbackContact.phone"
+            :href="fallbackPhoneHref"
+          >{{ formDefinition.fallbackContact.phone }}</a>
+        </div>
+
+        <div
+          class="asd20-public-form-modal__submit"
+          aria-live="polite"
+        >
+          <template v-if="!sending">
+            <recaptcha
+              v-if="captchaEnabled"
+              :sitekey="captchaSitekey"
+              :load-recaptcha-script="loadRecaptchaScript"
+              size="invisible"
+              @verify="captchaVerified"
+              @error="captchaFailed"
+              @expired="captchaExpired"
+            >
+              <asd20-button
+                :label="formDefinition.submitLabel"
+                horizontal
+                centered
+                bordered
+                @click="validateBeforeCaptcha"
+              />
+            </recaptcha>
+            <asd20-button
+              v-else
+              :label="formDefinition.submitLabel"
+              horizontal
+              centered
+              bordered
+              @click="submitForm('')"
+            />
+          </template>
+          <asd20-spinner
+            v-else
+            size="sm"
+          />
+        </div>
+
+        <div
+          v-if="feedbackMessage"
+          ref="feedback"
+          class="asd20-public-form-modal__feedback"
+          :role="feedbackRole"
+          tabindex="-1"
+        >
+          {{ feedbackMessage }}
+        </div>
+      </form>
+    </asd20-viewport>
+  </asd20-modal>
+</template>
+
+<script>
+import Asd20Button from '../../atoms/Asd20Button'
+import Asd20Spinner from '../../atoms/Asd20Spinner'
+import Asd20Viewport from '../../atoms/Asd20Viewport'
+import Asd20Modal from '../../molecules/Asd20Modal'
+import Asd20PublicFormField from '../../molecules/Asd20PublicFormField'
+import Recaptcha from '../../utils/Recaptcha'
+import {
+  createPublicFormValues,
+  normalizePublicFormDefinition,
+  validatePublicFormValues,
+} from '../../../helpers/publicFormDefinition'
+import {
+  fetchPublicFormDefinition,
+  normalizeFormId,
+  submitPublicForm,
+} from '../../../helpers/publicForms'
+import createComponentInstanceId from '../../../utils/createComponentInstanceId'
+
+const DEFAULT_CAPTCHA_SITEKEY = '6LfidKoUAAAAAFqr3QEbia3jIkecsZyxBYlMvWrX'
+
+export default {
+  name: 'Asd20PublicFormModal',
+  components: {
+    Asd20Button,
+    Asd20Modal,
+    Asd20PublicFormField,
+    Asd20Spinner,
+    Asd20Viewport,
+    Recaptcha,
+  },
+  props: {
+    open: { type: Boolean, default: false },
+    formId: { type: String, required: true },
+    definition: { type: Object, default: null },
+    endpoint: { type: String, default: '' },
+    functionsEndpoint: { type: String, default: '' },
+    captchaEnabled: { type: Boolean, default: true },
+    captchaSitekey: { type: String, default: DEFAULT_CAPTCHA_SITEKEY },
+    loadRecaptchaScript: { type: Boolean, default: true },
+    schemaClient: { type: Function, default: null },
+    submissionClient: { type: Function, default: null },
+  },
+  emits: ['dismiss', 'submitted', 'update:open'],
+  data() {
+    const instanceId = createComponentInstanceId('asd20-public-form')
+    return {
+      instanceId,
+      honeypotId: `${instanceId}-website`,
+      formDefinition: null,
+      values: {},
+      honeypot: '',
+      validationErrors: {},
+      validationAttempted: false,
+      loadingDefinition: false,
+      definitionError: '',
+      feedbackMessage: '',
+      feedbackRole: 'alert',
+      sending: false,
+      submissionSuccess: false,
+      loadSequence: 0,
+    }
+  },
+  computed: {
+    modalTitle() {
+      return this.formDefinition?.title || 'Public Form'
+    },
+    errorEntries() {
+      if (!this.formDefinition) return []
+      return this.formDefinition.fields
+        .filter(field => this.validationErrors[field.name]?.length)
+        .map(field => ({
+          name: field.name,
+          messages: this.validationErrors[field.name],
+        }))
+    },
+    hasFallbackContact() {
+      const fallback = this.formDefinition?.fallbackContact
+      return Boolean(fallback?.email || fallback?.phone)
+    },
+    fallbackPhoneHref() {
+      const phone = this.formDefinition?.fallbackContact?.phone || ''
+      return `tel:${phone.replace(/[^+\d]/g, '')}`
+    },
+  },
+  watch: {
+    open: {
+      immediate: true,
+      handler(value) {
+        if (value) this.prepareForm()
+        else this.loadSequence += 1
+      },
+    },
+    definition: {
+      deep: true,
+      handler() {
+        if (this.open) this.prepareForm()
+      },
+    },
+    formId() {
+      if (this.open) this.prepareForm()
+    },
+  },
+  methods: {
+    resolveRuntimeConfig() {
+      return (
+        this.$config ||
+        this.$?.appContext?.config?.globalProperties?.$config ||
+        {}
+      )
+    },
+    clientOptions() {
+      return {
+        endpoint: this.endpoint,
+        functionsEndpoint: this.functionsEndpoint,
+        runtimeConfig: this.resolveRuntimeConfig(),
+      }
+    },
+    async prepareForm() {
+      const sequence = ++this.loadSequence
+      this.loadingDefinition = true
+      this.definitionError = ''
+      this.feedbackMessage = ''
+      this.submissionSuccess = false
+      this.validationErrors = {}
+      this.validationAttempted = false
+      this.honeypot = ''
+
+      try {
+        const expectedId = normalizeFormId(this.formId)
+        const rawDefinition = this.definition
+          ? this.definition
+          : await (this.schemaClient || fetchPublicFormDefinition)(
+              expectedId,
+              this.clientOptions()
+            )
+        const normalized = normalizePublicFormDefinition(rawDefinition)
+        if (normalized.id !== expectedId)
+          throw new Error(
+            'The public form definition does not match the request.'
+          )
+        if (sequence !== this.loadSequence) return
+
+        this.formDefinition = normalized
+        this.values = createPublicFormValues(normalized)
+      } catch (_error) {
+        if (sequence !== this.loadSequence) return
+        this.formDefinition = null
+        this.definitionError =
+          'This form could not be loaded. Please try again later or use another contact option on this page.'
+        this.$nextTick(() => this.$refs.definitionError?.focus?.())
+      } finally {
+        if (sequence === this.loadSequence) this.loadingDefinition = false
+      }
+    },
+    fieldId(name) {
+      return `${this.instanceId}-${name}`
+    },
+    updateValue(name, value) {
+      this.values[name] = value
+      if (this.validationAttempted) this.validate(false)
+    },
+    validate(focusSummary = true) {
+      if (!this.formDefinition) return false
+      const result = validatePublicFormValues(this.formDefinition, this.values)
+      this.values = result.values
+      this.validationErrors = result.errors
+      this.validationAttempted = true
+
+      if (!result.valid && focusSummary) {
+        this.$nextTick(() => this.$refs.errorSummary?.focus?.())
+      }
+      return result.valid
+    },
+    validateBeforeCaptcha(event) {
+      if (this.sending || !this.validate()) {
+        event?.preventDefault?.()
+        return false
+      }
+      return true
+    },
+    focusField(name) {
+      document.getElementById(this.fieldId(name))?.focus?.()
+    },
+    captchaVerified(token) {
+      if (token) this.submitForm(token)
+    },
+    captchaFailed() {
+      this.showFeedback(
+        'The verification service could not start. Please try again or use the contact options below.'
+      )
+    },
+    captchaExpired() {
+      this.showFeedback(
+        'The verification expired. Please submit the form again.'
+      )
+    },
+    failureMessage(error) {
+      const status = Number(error?.response?.status || 0)
+      const serverMessage = error?.response?.data?.error
+      if (status === 400 && typeof serverMessage === 'string')
+        return serverMessage
+      if (status === 403)
+        return 'The verification was not accepted. Please try again.'
+      if (status === 429) {
+        return 'Too many submissions were received recently. Please wait and try again, or use the contact options below.'
+      }
+      if (status === 502) {
+        return 'The form could not be delivered right now. Please try again later or use the contact options below.'
+      }
+      if (status === 503) {
+        return 'This form is temporarily unavailable. Please use the contact options below.'
+      }
+      return 'Something went wrong while submitting the form. Please try again later or use the contact options below.'
+    },
+    showFeedback(message, role = 'alert') {
+      this.feedbackMessage = message
+      this.feedbackRole = role
+      this.$nextTick(() => this.$refs.feedback?.focus?.())
+    },
+    async submitForm(captchaToken = '') {
+      if (this.sending || !this.validate()) return
+      if (this.captchaEnabled && !captchaToken) {
+        this.showFeedback('Verification is required before submitting this form.')
+        return
+      }
+
+      this.sending = true
+      this.feedbackMessage = ''
+      try {
+        const payload = {
+          ...this.values,
+          website: this.honeypot,
+          captchaToken,
+        }
+        await (this.submissionClient || submitPublicForm)(
+          this.formDefinition.id,
+          payload,
+          this.clientOptions()
+        )
+        this.submissionSuccess = true
+        this.$emit('submitted', {
+          formId: this.formDefinition.id,
+          definitionVersion: this.formDefinition.version,
+        })
+      } catch (error) {
+        this.showFeedback(this.failureMessage(error))
+      } finally {
+        this.sending = false
+      }
+    },
+    dismiss() {
+      this.$emit('dismiss')
+      this.$emit('update:open', false)
+    },
+  },
+}
+</script>
+
+<style lang="scss" scoped>
+@use '../../../design/component-stack' as *;
+@use '../../../design/typography' as *;
+
+.asd20-public-form-modal {
+  @include typography;
+
+  & :deep(.asd20-modal__content .asd20-viewport) {
+    padding: space(1);
+  }
+
+  & :deep(.asd20-text-area-input textarea) {
+    font-family: Arial, sans-serif;
+    font-size: 1rem;
+  }
+
+  &__state,
+  &__submit {
+    align-items: center;
+    display: flex;
+    gap: space(0.25);
+    justify-content: center;
+    min-height: space(2);
+  }
+
+  &__error-summary,
+  &__feedback,
+  &__success {
+    font-weight: 600;
+    margin: space(0.5) 0;
+  }
+
+  &__error-summary {
+    border: 2px solid asd20-swatch('emergency', -1);
+    padding: space(0.5);
+
+    p {
+      margin-top: 0;
+    }
+  }
+
+  &__success {
+    font-size: 1.1rem;
+    text-align: center;
+  }
+
+  &__fallback {
+    display: flex;
+    flex-direction: column;
+    margin: space(0.5) 0;
+
+    p {
+      margin-bottom: space(0.125);
+    }
+  }
+
+  &__feedback {
+    text-align: center;
+  }
+
+  &__honeypot {
+    clip: rect(0, 0, 0, 0);
+    height: 1px;
+    margin: -1px;
+    overflow: hidden;
+    position: absolute;
+    width: 1px;
+  }
+}
+
+@media (min-width: 1024px) {
+  .asd20-public-form-modal {
+    & :deep(.asd20-modal) {
+      margin-top: auto;
+      margin-bottom: auto;
+      max-width: 40vw;
+    }
+  }
+}
+</style>

package/src/helpers/publicFormDefinition.js

@@ -0,0 +1,236 @@
+export const SUPPORTED_PUBLIC_FORM_FIELD_TYPES = Object.freeze([
+  'text',
+  'email',
+  'tel',
+  'date',
+  'textarea',
+  'select',
+  'radio',
+  'checkbox',
+])
+
+const FIELD_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_]*$/
+const FORM_ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+const OPTION_VALUE_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/
+const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+const MAX_FIELDS = 50
+const MAX_OPTIONS = 100
+const MAX_TEXT_LENGTH = 10000
+
+function boundedText(value, label, maximum, required = false) {
+  if (value == null && !required) return ''
+  if (typeof value !== 'string') throw new Error(`${label} must be text.`)
+  const normalized = value.trim()
+  if (required && !normalized) throw new Error(`${label} is required.`)
+  if (normalized.length > maximum) throw new Error(`${label} is too long.`)
+  return normalized
+}
+
+function optionalLength(value, label) {
+  if (value == null) return undefined
+  if (!Number.isInteger(value) || value < 0 || value > MAX_TEXT_LENGTH) {
+    throw new Error(`${label} is invalid.`)
+  }
+  return value
+}
+
+function normalizeOptions(field) {
+  if (!['select', 'radio'].includes(field.type)) return undefined
+  if (
+    !Array.isArray(field.options) ||
+    !field.options.length ||
+    field.options.length > MAX_OPTIONS
+  ) {
+    throw new Error(`${field.label} must have approved choices.`)
+  }
+
+  const seen = new Set()
+  return field.options.map(option => {
+    const label = boundedText(option?.label, 'Option label', 200, true)
+    const value = boundedText(option?.value, 'Option value', 100, true)
+    if (!OPTION_VALUE_PATTERN.test(value))
+      throw new Error(`${field.label} has an invalid choice ID.`)
+    if (seen.has(value))
+      throw new Error(`${field.label} has duplicate choices.`)
+    seen.add(value)
+    return { label, value }
+  })
+}
+
+function normalizeField(field) {
+  if (!field || typeof field !== 'object' || Array.isArray(field)) {
+    throw new Error('The public form contains an invalid field.')
+  }
+
+  const name = boundedText(field.name, 'Field name', 64, true)
+  if (!FIELD_NAME_PATTERN.test(name))
+    throw new Error('The public form contains an invalid field name.')
+
+  const type = boundedText(field.type, 'Field type', 30, true)
+  if (!SUPPORTED_PUBLIC_FORM_FIELD_TYPES.includes(type)) {
+    throw new Error(
+      `The public form contains an unsupported field type: ${type}.`
+    )
+  }
+
+  const normalized = {
+    name,
+    type,
+    label: boundedText(field.label, 'Field label', 200, true),
+    helpText: boundedText(field.helpText, 'Field help text', 2000),
+    required: field.required === true,
+    minLength: optionalLength(field.minLength, 'Minimum length'),
+    maxLength: optionalLength(field.maxLength, 'Maximum length'),
+    autocomplete: boundedText(field.autocomplete, 'Autocomplete value', 100),
+    options: undefined,
+  }
+
+  if (
+    normalized.minLength != null &&
+    normalized.maxLength != null &&
+    normalized.minLength > normalized.maxLength
+  ) {
+    throw new Error(`${normalized.label} has invalid length limits.`)
+  }
+
+  normalized.options = normalizeOptions({
+    ...field,
+    type,
+    label: normalized.label,
+  })
+  return normalized
+}
+
+export function normalizePublicFormDefinition(definition) {
+  if (
+    !definition ||
+    typeof definition !== 'object' ||
+    Array.isArray(definition)
+  ) {
+    throw new Error('The public form definition is invalid.')
+  }
+  if (
+    !Array.isArray(definition.fields) ||
+    !definition.fields.length ||
+    definition.fields.length > MAX_FIELDS
+  ) {
+    throw new Error('The public form must contain approved fields.')
+  }
+
+  const fields = definition.fields.map(normalizeField)
+  const names = new Set(fields.map(field => field.name))
+  if (names.size !== fields.length)
+    throw new Error('The public form contains duplicate field names.')
+
+  const version = Number(definition.version)
+  if (!Number.isInteger(version) || version < 1)
+    throw new Error('The public form version is invalid.')
+
+  const fallbackContact = definition.fallbackContact
+  let normalizedFallback
+  if (fallbackContact != null) {
+    if (typeof fallbackContact !== 'object' || Array.isArray(fallbackContact)) {
+      throw new Error('The public form fallback contact is invalid.')
+    }
+    const email = boundedText(fallbackContact.email, 'Fallback email', 320)
+    const phone = boundedText(fallbackContact.phone, 'Fallback phone', 50)
+    if (email && !EMAIL_PATTERN.test(email))
+      throw new Error('The public form fallback email is invalid.')
+    normalizedFallback = { email, phone }
+  }
+
+  const id = boundedText(definition.id, 'Form ID', 100, true)
+  if (!FORM_ID_PATTERN.test(id)) throw new Error('The public form ID is invalid.')
+
+  return {
+    id,
+    version,
+    title: boundedText(definition.title, 'Form title', 200, true),
+    introduction: boundedText(
+      definition.introduction,
+      'Form introduction',
+      2000
+    ),
+    submitLabel: boundedText(definition.submitLabel, 'Submit label', 100, true),
+    successMessage: boundedText(
+      definition.successMessage,
+      'Success message',
+      1000,
+      true
+    ),
+    fallbackContact: normalizedFallback,
+    fields,
+  }
+}
+
+export function createPublicFormValues(definition) {
+  return Object.fromEntries(
+    definition.fields.map(field => [
+      field.name,
+      field.type === 'checkbox' ? false : '',
+    ])
+  )
+}
+
+function validDate(value) {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) return false
+  const [year, month, day] = value.split('-').map(Number)
+  const date = new Date(Date.UTC(year, month - 1, day))
+  return (
+    date.getUTCFullYear() === year &&
+    date.getUTCMonth() === month - 1 &&
+    date.getUTCDate() === day
+  )
+}
+
+export function validatePublicFormValues(definition, sourceValues = {}) {
+  const errors = {}
+  const values = {}
+
+  for (const field of definition.fields) {
+    const rawValue = sourceValues[field.name]
+    const fieldErrors = []
+
+    if (field.type === 'checkbox') {
+      const value = rawValue === true
+      values[field.name] = value
+      if (field.required && !value)
+        fieldErrors.push(`${field.label} is required.`)
+    } else {
+      const hasInvalidType = rawValue != null && typeof rawValue !== 'string'
+      const value = typeof rawValue === 'string' ? rawValue.trim() : ''
+      values[field.name] = field.type === 'email' ? value.toLowerCase() : value
+
+      if (hasInvalidType) fieldErrors.push(`${field.label} must be text.`)
+      else if (field.required && !value)
+        fieldErrors.push(`${field.label} is required.`)
+      if (value && field.minLength != null && value.length < field.minLength) {
+        fieldErrors.push(
+          `${field.label} must be at least ${field.minLength} characters.`
+        )
+      }
+      if (value && field.maxLength != null && value.length > field.maxLength) {
+        fieldErrors.push(
+          `${field.label} must be ${field.maxLength} characters or fewer.`
+        )
+      }
+      if (value && field.type === 'email' && !EMAIL_PATTERN.test(value)) {
+        fieldErrors.push('Enter a valid email address.')
+      }
+      if (value && field.type === 'date' && !validDate(value)) {
+        fieldErrors.push(`Enter a valid ${field.label.toLowerCase()}.`)
+      }
+      if (value && ['select', 'radio'].includes(field.type)) {
+        const allowedValues = new Set(
+          (field.options || []).map(option => option.value)
+        )
+        if (!allowedValues.has(value))
+          fieldErrors.push(`Select a valid ${field.label.toLowerCase()}.`)
+      }
+    }
+
+    if (fieldErrors.length) errors[field.name] = fieldErrors
+  }
+
+  return { values, errors, valid: Object.keys(errors).length === 0 }
+}

package/src/helpers/publicForms.js

@@ -0,0 +1,66 @@
+import axios from 'axios'
+
+import { normalizeBaseUrl, resolveRuntimeConfigValue } from './runtimeConfig'
+
+const PUBLIC_FORMS_ROUTE = '/api/public-forms'
+const PUBLIC_FORM_ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+
+function normalizeFormId(formId) {
+  const normalized =
+    typeof formId === 'string' ? formId.trim().toLowerCase() : ''
+  if (!PUBLIC_FORM_ID_PATTERN.test(normalized)) {
+    throw new Error('The public form ID is invalid.')
+  }
+  return normalized
+}
+
+export function resolvePublicFormsEndpoint({
+  endpoint = null,
+  functionsEndpoint = null,
+  runtimeConfig = {},
+} = {}) {
+  const explicitEndpoint = resolveRuntimeConfigValue({
+    explicitValue: endpoint,
+    runtimeConfig,
+    runtimeConfigKeys: ['publicFormsEndpoint'],
+    envKeys: ['PUBLIC_FORMS_ENDPOINT'],
+  })
+  if (explicitEndpoint) return normalizeBaseUrl(explicitEndpoint)
+
+  const resolvedFunctionsEndpoint = resolveRuntimeConfigValue({
+    explicitValue: functionsEndpoint,
+    runtimeConfig,
+    runtimeConfigKeys: ['functionsEndpoint'],
+    envKeys: ['FUNCTIONS_ENDPOINT'],
+  })
+  const baseUrl = normalizeBaseUrl(resolvedFunctionsEndpoint)
+  return baseUrl ? `${baseUrl}${PUBLIC_FORMS_ROUTE}` : null
+}
+
+export function resolvePublicFormEndpoints(formId, options = {}) {
+  const normalizedFormId = normalizeFormId(formId)
+  const baseEndpoint = resolvePublicFormsEndpoint(options)
+  if (!baseEndpoint) return { schema: null, submissions: null }
+
+  const schema = `${baseEndpoint}/${normalizedFormId}`
+  return { schema, submissions: `${schema}/submissions` }
+}
+
+export async function fetchPublicFormDefinition(formId, options = {}) {
+  const { schema } = resolvePublicFormEndpoints(formId, options)
+  if (!schema) throw new Error('The public forms endpoint is not configured.')
+
+  const response = await axios.get(schema)
+  return response.data
+}
+
+export async function submitPublicForm(formId, submission, options = {}) {
+  const { submissions } = resolvePublicFormEndpoints(formId, options)
+  if (!submissions)
+    throw new Error('The public forms endpoint is not configured.')
+
+  const response = await axios.post(submissions, submission)
+  return response.data
+}
+
+export { normalizeFormId }