@duffcloudservices/site-forms 0.1.0

package/src/schema/form-definition.schema.json

@@ -0,0 +1,633 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://duffcloudservices.com/schemas/form-definition.schema.json",
+  "title": "PortalFormDefinition",
+  "type": "object",
+  "description": "Portable form definition. This schema is the source of truth for\nboth the portal CRUD APIs and the `.dcs/forms/<formId>.yaml`\nfiles consumed by customer-site builds via `<DcsForm/>`.\n",
+  "required": [
+    "formId",
+    "title",
+    "submission",
+    "fields"
+  ],
+  "properties": {
+    "formId": {
+      "type": "string",
+      "description": "Kebab-case identifier, unique per site.",
+      "pattern": "^[a-z0-9][a-z0-9-]*$",
+      "minLength": 1,
+      "maxLength": 80,
+      "example": "contact"
+    },
+    "title": {
+      "type": "string",
+      "description": "Human-readable form title shown in the portal and rendered as the form heading.",
+      "minLength": 1,
+      "maxLength": 200,
+      "example": "Contact Us"
+    },
+    "description": {
+      "type": "string",
+      "description": "Optional descriptive text rendered above the fields.",
+      "maxLength": 2000
+    },
+    "submitLabel": {
+      "type": "string",
+      "description": "Label for the submit button. Defaults to \"Send\" client-side.",
+      "maxLength": 80,
+      "example": "Send message"
+    },
+    "successMessage": {
+      "type": "string",
+      "description": "Confirmation message shown after a successful submission.",
+      "maxLength": 2000,
+      "example": "Thanks — we'll be in touch shortly."
+    },
+    "submission": {
+      "$ref": "#/definitions/PortalFormSubmissionConfig"
+    },
+    "steps": {
+      "type": "array",
+      "description": "Optional multi-step grouping. When omitted, fields render as a single page.",
+      "items": {
+        "$ref": "#/definitions/PortalFormStep"
+      }
+    },
+    "fields": {
+      "type": "array",
+      "description": "Flat list of all fields in the form. When `steps` is present,\nevery field referenced from a step's `fieldIds` must exist here.\n",
+      "items": {
+        "$ref": "#/definitions/PortalFormField"
+      }
+    },
+    "version": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Monotonically increasing version, bumped on each save."
+    },
+    "createdAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Form creation timestamp."
+    },
+    "updatedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Last modification timestamp."
+    }
+  },
+  "definitions": {
+    "PortalFormFieldType": {
+      "type": "string",
+      "description": "Field type controlling input rendering and validation. Includes\nlayout-only types (`section-heading`, `html-block`) that render\ndecorative content rather than capturing values, and `hidden`\nfor prefilled values not displayed to the user.\n",
+      "enum": [
+        "text",
+        "email",
+        "tel",
+        "textarea",
+        "select",
+        "multiselect",
+        "radio",
+        "checkbox",
+        "checkbox-group",
+        "date",
+        "file",
+        "hidden",
+        "section-heading",
+        "html-block"
+      ]
+    },
+    "PortalFormFieldWidth": {
+      "type": "string",
+      "description": "Layout hint for the field within its row.",
+      "enum": [
+        "full",
+        "half",
+        "third"
+      ]
+    },
+    "PortalFormFieldOption": {
+      "type": "object",
+      "description": "A single option for select / radio / checkbox-group fields.",
+      "required": [
+        "value",
+        "label"
+      ],
+      "properties": {
+        "value": {
+          "type": "string",
+          "description": "Submitted value for this option."
+        },
+        "label": {
+          "type": "string",
+          "description": "Human-readable label shown to the user."
+        }
+      }
+    },
+    "PortalFormFieldValidation": {
+      "type": "object",
+      "description": "Optional validation rules applied to a field's value.",
+      "properties": {
+        "regex": {
+          "type": "string",
+          "description": "ECMAScript-compatible pattern the value must match."
+        },
+        "minLength": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Minimum string length (text-like fields only)."
+        },
+        "maxLength": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Maximum string length (text-like fields only)."
+        },
+        "min": {
+          "type": "number",
+          "description": "Minimum numeric / date value."
+        },
+        "max": {
+          "type": "number",
+          "description": "Maximum numeric / date value."
+        },
+        "accept": {
+          "type": "array",
+          "description": "Accepted MIME types or file extensions for `file` fields.",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "PortalFormFieldVisibleIf": {
+      "type": "object",
+      "description": "Single-predicate visibility rule. The field is shown only when\nthe referenced sibling field's value equals `equals`. Future\nrevisions may extend this with AND / OR composition; clients\nshould treat unknown extra properties as opaque.\n",
+      "required": [
+        "fieldId",
+        "equals"
+      ],
+      "properties": {
+        "fieldId": {
+          "type": "string",
+          "description": "ID of the sibling field whose value gates visibility."
+        },
+        "equals": {
+          "description": "Value (string, number, or boolean) the sibling field must equal.",
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "number"
+            },
+            {
+              "type": "boolean"
+            }
+          ]
+        }
+      }
+    },
+    "PortalFormField": {
+      "type": "object",
+      "description": "A single field within a form definition.",
+      "required": [
+        "id",
+        "type",
+        "label"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Kebab-case identifier, unique within the form.",
+          "pattern": "^[a-z0-9][a-z0-9-]*$",
+          "minLength": 1,
+          "maxLength": 80
+        },
+        "type": {
+          "$ref": "#/definitions/PortalFormFieldType"
+        },
+        "label": {
+          "type": "string",
+          "description": "Human-readable label rendered above the input.",
+          "minLength": 1,
+          "maxLength": 200
+        },
+        "helpText": {
+          "type": "string",
+          "description": "Optional helper / description text shown beneath the label.",
+          "maxLength": 500
+        },
+        "placeholder": {
+          "type": "string",
+          "description": "Optional placeholder shown inside empty inputs.",
+          "maxLength": 200
+        },
+        "defaultValue": {
+          "description": "Optional default value (string, number, boolean, or array of strings).",
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "number"
+            },
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          ]
+        },
+        "required": {
+          "type": "boolean",
+          "default": false,
+          "description": "Whether the field must be supplied to submit the form."
+        },
+        "width": {
+          "allOf": [
+            {
+              "$ref": "#/definitions/PortalFormFieldWidth"
+            }
+          ],
+          "default": "full"
+        },
+        "options": {
+          "type": "array",
+          "description": "Options for `select`, `multiselect`, `radio`, `checkbox-group` fields.",
+          "items": {
+            "$ref": "#/definitions/PortalFormFieldOption"
+          }
+        },
+        "validation": {
+          "$ref": "#/definitions/PortalFormFieldValidation"
+        },
+        "visibleIf": {
+          "$ref": "#/definitions/PortalFormFieldVisibleIf"
+        },
+        "phi": {
+          "type": "boolean",
+          "default": false,
+          "description": "Marks the field as collecting Protected Health Information.\nWhen true the value must never appear in notification emails\nor logs and the owning site must be in the Medical category\n(see `compliance.instructions.md`).\n"
+        },
+        "html": {
+          "type": "string",
+          "description": "Sanitized HTML body for `html-block` fields. Ignored for\nother field types.\n",
+          "maxLength": 10000
+        }
+      }
+    },
+    "PortalFormStep": {
+      "type": "object",
+      "description": "Optional grouping for multi-step (wizard-style) forms such as\nthe KT Braun estate-planning questionnaires. When `steps` is\nomitted on a form, all fields render as a single page.\n",
+      "required": [
+        "id",
+        "title",
+        "fieldIds"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Kebab-case step identifier, unique within the form.",
+          "pattern": "^[a-z0-9][a-z0-9-]*$",
+          "minLength": 1,
+          "maxLength": 80
+        },
+        "title": {
+          "type": "string",
+          "description": "Step title shown in the wizard header.",
+          "minLength": 1,
+          "maxLength": 200
+        },
+        "description": {
+          "type": "string",
+          "description": "Optional descriptive text shown below the step title.",
+          "maxLength": 1000
+        },
+        "fieldIds": {
+          "type": "array",
+          "description": "Ordered list of field IDs that belong to this step.",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9-]*$"
+          }
+        }
+      }
+    },
+    "PortalFormSubmissionLeadConfig": {
+      "type": "object",
+      "required": [
+        "kind"
+      ],
+      "description": "Routes submissions into the existing PortalLeads pipeline.",
+      "properties": {
+        "kind": {
+          "type": "string",
+          "enum": [
+            "lead"
+          ]
+        },
+        "category": {
+          "type": "string",
+          "description": "Service category id used to route the lead."
+        }
+      }
+    },
+    "PortalFormSubmissionEmailConfig": {
+      "type": "object",
+      "required": [
+        "kind",
+        "to"
+      ],
+      "description": "Routes submissions as a notification email to the listed recipients.",
+      "properties": {
+        "kind": {
+          "type": "string",
+          "enum": [
+            "email"
+          ]
+        },
+        "to": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "format": "email"
+          },
+          "description": "Recipient email addresses."
+        },
+        "subjectTemplate": {
+          "type": "string",
+          "description": "Optional subject-line template. Use `{title}` to interpolate\nthe form's title; values are intentionally not interpolated\ninto the subject line for compliance reasons.\n",
+          "maxLength": 200
+        }
+      }
+    },
+    "PortalFormSubmissionWebhookConfig": {
+      "type": "object",
+      "required": [
+        "kind",
+        "url"
+      ],
+      "description": "Posts the submission JSON to a third-party webhook.",
+      "properties": {
+        "kind": {
+          "type": "string",
+          "enum": [
+            "webhook"
+          ]
+        },
+        "url": {
+          "type": "string",
+          "format": "uri",
+          "description": "HTTPS endpoint receiving the signed POST."
+        },
+        "signingSecretRef": {
+          "type": "string",
+          "description": "Name of the Key Vault secret used to HMAC-sign the request.\nThe secret value is never returned in API responses.\n"
+        }
+      }
+    },
+    "PortalFormSubmissionConfig": {
+      "description": "Discriminated union of submission destinations. Exactly one of\n`lead`, `email`, or `webhook` shapes is used based on `kind`.\n",
+      "oneOf": [
+        {
+          "$ref": "#/definitions/PortalFormSubmissionLeadConfig"
+        },
+        {
+          "$ref": "#/definitions/PortalFormSubmissionEmailConfig"
+        },
+        {
+          "$ref": "#/definitions/PortalFormSubmissionWebhookConfig"
+        }
+      ],
+      "discriminator": {
+        "propertyName": "kind",
+        "mapping": {
+          "lead": "#/definitions/PortalFormSubmissionLeadConfig",
+          "email": "#/definitions/PortalFormSubmissionEmailConfig",
+          "webhook": "#/definitions/PortalFormSubmissionWebhookConfig"
+        }
+      }
+    },
+    "PortalFormSummary": {
+      "type": "object",
+      "description": "List-row projection of a form definition.",
+      "required": [
+        "formId",
+        "title",
+        "fieldCount"
+      ],
+      "properties": {
+        "formId": {
+          "type": "string",
+          "description": "Kebab-case identifier.",
+          "pattern": "^[a-z0-9][a-z0-9-]*$",
+          "example": "contact"
+        },
+        "title": {
+          "type": "string",
+          "description": "Human-readable title.",
+          "example": "Contact Us"
+        },
+        "description": {
+          "type": "string",
+          "description": "Optional descriptive text."
+        },
+        "fieldCount": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Number of input-bearing fields in the form.",
+          "example": 4
+        },
+        "attachedPageSlugs": {
+          "type": "array",
+          "description": "Slugs of pages that currently reference this form via `formId`.",
+          "items": {
+            "type": "string"
+          }
+        },
+        "submissionKind": {
+          "type": "string",
+          "enum": [
+            "lead",
+            "email",
+            "webhook"
+          ],
+          "description": "Submission destination kind."
+        },
+        "lastUpdated": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Last modification timestamp."
+        }
+      }
+    },
+    "PortalCreateFormRequest": {
+      "type": "object",
+      "description": "Payload for creating a new form definition.",
+      "required": [
+        "formId",
+        "title",
+        "submission",
+        "fields"
+      ],
+      "properties": {
+        "formId": {
+          "type": "string",
+          "description": "Kebab-case identifier, unique per site.",
+          "pattern": "^[a-z0-9][a-z0-9-]*$",
+          "minLength": 1,
+          "maxLength": 80
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200
+        },
+        "description": {
+          "type": "string",
+          "maxLength": 2000
+        },
+        "submitLabel": {
+          "type": "string",
+          "maxLength": 80
+        },
+        "successMessage": {
+          "type": "string",
+          "maxLength": 2000
+        },
+        "submission": {
+          "$ref": "#/definitions/PortalFormSubmissionConfig"
+        },
+        "steps": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/PortalFormStep"
+          }
+        },
+        "fields": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/PortalFormField"
+          }
+        }
+      }
+    },
+    "PortalUpdateFormRequest": {
+      "type": "object",
+      "description": "Payload for updating an existing form definition. The `formId`\nis taken from the URL; supplying it in the body is optional and,\nif present, must match the path.\n",
+      "properties": {
+        "formId": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9-]*$",
+          "minLength": 1,
+          "maxLength": 80,
+          "description": "Optional echo of the path formId; must match if provided."
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200
+        },
+        "description": {
+          "type": "string",
+          "maxLength": 2000
+        },
+        "submitLabel": {
+          "type": "string",
+          "maxLength": 80
+        },
+        "successMessage": {
+          "type": "string",
+          "maxLength": 2000
+        },
+        "submission": {
+          "$ref": "#/definitions/PortalFormSubmissionConfig"
+        },
+        "steps": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/PortalFormStep"
+          }
+        },
+        "fields": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/PortalFormField"
+          }
+        },
+        "expectedVersion": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Optional optimistic-concurrency token. When supplied, the\nupdate is rejected with 409 if the stored form's `version`\nno longer matches.\n"
+        }
+      }
+    },
+    "PortalDuplicateFormRequest": {
+      "type": "object",
+      "description": "Payload for cloning an existing form under a new formId.",
+      "required": [
+        "formId"
+      ],
+      "properties": {
+        "formId": {
+          "type": "string",
+          "description": "Target kebab-case formId for the cloned form.",
+          "pattern": "^[a-z0-9][a-z0-9-]*$",
+          "minLength": 1,
+          "maxLength": 80
+        },
+        "title": {
+          "type": "string",
+          "description": "Optional title override; defaults to `<source title> (copy)`.",
+          "minLength": 1,
+          "maxLength": 200
+        }
+      }
+    },
+    "PortalFormResponse": {
+      "type": "object",
+      "description": "Full form definition response.",
+      "required": [
+        "form"
+      ],
+      "properties": {
+        "form": {
+          "$ref": "#/definitions/PortalFormDefinition"
+        },
+        "attachedPageSlugs": {
+          "type": "array",
+          "description": "Slugs of pages that currently reference this form via `formId`.",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "PortalFormListResponse": {
+      "type": "object",
+      "required": [
+        "forms",
+        "totalCount"
+      ],
+      "properties": {
+        "forms": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/PortalFormSummary"
+          }
+        },
+        "totalCount": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Total number of forms matching the query.",
+          "example": 3
+        }
+      }
+    }
+  }
+}

package/src/schema/validate.ts

@@ -0,0 +1,58 @@
+/**
+ * Validates a loaded form definition against the form-definition JSON
+ * Schema emitted by `@dcs/contracts`. Dev-only — failures are logged
+ * via `console.warn` rather than thrown so a malformed YAML never
+ * takes down a customer site in production.
+ *
+ * Schema is bundled as a snapshot of
+ * `contracts/dist/form-definition.schema.json` to avoid a runtime
+ * dependency on the contracts build output.
+ */
+import Ajv, { type ErrorObject, type ValidateFunction } from 'ajv'
+import addFormats from 'ajv-formats'
+import schema from './form-definition.schema.json'
+import type { PortalFormDefinition } from '../types'
+
+let validator: ValidateFunction | null = null
+
+function getValidator(): ValidateFunction {
+  if (validator) return validator
+  const ajv = new Ajv({
+    allErrors: true,
+    strict: false,
+    discriminator: false,
+  })
+  addFormats(ajv)
+  validator = ajv.compile(schema as object)
+  return validator
+}
+
+export interface SchemaValidationResult {
+  valid: boolean
+  errors: ErrorObject[]
+}
+
+export function validateFormDefinition(
+  def: PortalFormDefinition | unknown,
+): SchemaValidationResult {
+  const v = getValidator()
+  const valid = v(def) as boolean
+  return { valid, errors: valid ? [] : (v.errors ?? []) }
+}
+
+/** Logs a `console.warn` when invalid, but only when `import.meta.env.DEV`. */
+export function warnIfInvalid(
+  formId: string,
+  def: PortalFormDefinition | unknown,
+  isDev: boolean,
+): SchemaValidationResult {
+  const result = validateFormDefinition(def)
+  if (!result.valid && isDev) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[@duffcloudservices/site-forms] Form "${formId}" failed schema validation:`,
+      result.errors,
+    )
+  }
+  return result
+}

package/src/shims.d.ts

@@ -0,0 +1,10 @@
+declare module '*.vue' {
+  import type { DefineComponent } from 'vue'
+  const component: DefineComponent<{}, {}, unknown>
+  export default component
+}
+
+declare module '*.json' {
+  const value: unknown
+  export default value
+}