@duffcloudservices/site-forms 0.1.0 → 0.1.2

package/README.md

@@ -1,213 +1,260 @@
-# @duffcloudservices/site-forms
-
-Shared `<DcsForm/>` runtime for DCS customer sites. Renders a managed
-form definition (created in the portal Form Manager) from a build-time
-`.dcs/forms/<formId>.yaml` snapshot, validates user input, and posts
-submissions to the public site-forms API.
-
-This is the single import surface for managed-form runtime code on
-customer sites — do not redefine field components per site.
-
-> **Inside the `dcs-again` workspace** the package is also reachable
-> as `@duffcloudservices/site-forms` via `workspace:*` (the workspace
-> name and the published name are the same).
-> **In sibling customer-site repos** install the published package
-> from public npm — see [`PUBLISHING.md`](./PUBLISHING.md) for the
-> consumption story and registry setup.
-
-## Install
-
-### In a workspace app (inside `dcs-again`)
-
-```jsonc
-// portal/package.json
-{
-  "dependencies": {
-    "@duffcloudservices/site-forms": "workspace:*"
-  }
-}
-```
-
-Then `pnpm install` from the repo root.
-
-### In a sibling customer-site repo (e.g. `ktbraunlaw`, `kept`)
-
-```powershell
-pnpm add @duffcloudservices/site-forms
-```
-
-See [`PUBLISHING.md`](./PUBLISHING.md) for the registry, version, and
-release-workflow details.
-
-## Vite setup
-
-Two pieces are required in the consuming site:
-
-1. **`vite-plugin-yaml`** so `import.meta.glob('/.dcs/forms/*.yaml', { eager: true, import: 'default' })` returns parsed objects:
-
-   ```ts
-   // vite.config.ts
-   import yaml from '@modyfi/vite-plugin-yaml'
-
-   export default defineConfig({
-     plugins: [vue(), yaml()],
-   })
-   ```
-
-   Without it, the loader falls back to parsing raw strings via
-   `js-yaml`, which works but pays the parse cost at boot.
-
-2. **Env vars** the runtime reads:
-
-   | Variable                | Purpose                                              |
-   | ----------------------- | ---------------------------------------------------- |
-   | `VITE_DCS_PUBLIC_API`   | Base URL of the DCS public API (no trailing slash). |
-   | `VITE_DCS_SITE_SLUG`    | Default site slug used when the prop is omitted.    |
-
-## Usage
-
-Place a YAML file at `<site>/.dcs/forms/contact.yaml`:
-
-```yaml
-formId: contact
-title: Contact Us
-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
-    required: true
-```
-
-Then in any page component:
-
-```vue
-<script setup lang="ts">
-import { DcsForm } from '@duffcloudservices/site-forms'
-</script>
-
-<template>
-  <DcsForm
-    form-id="contact"
-    @submit-success="onSuccess"
-    @submit-error="onError"
-  />
-</template>
-```
-
-## Props
-
-| Prop                 | Type                              | Default                                | Notes                                                       |
-| -------------------- | --------------------------------- | -------------------------------------- | ----------------------------------------------------------- |
-| `formId`             | `string` (required)               | —                                      | Matches `.dcs/forms/<formId>.yaml`.                         |
-| `siteSlug`           | `string`                          | `import.meta.env.VITE_DCS_SITE_SLUG`   | Path segment in the submission URL.                         |
-| `definitionOverride` | `PortalFormDefinition`            | —                                      | Used by the portal preview iframe to show in-flight edits.  |
-| `apiBase`            | `string`                          | `import.meta.env.VITE_DCS_PUBLIC_API`  | Override for tests / non-prod environments.                 |
-| `captchaToken`       | `string`                          | —                                      | Attached to the submission payload when set.                |
-| `formsModules`       | `Record<string, unknown>`         | `import.meta.glob(...)`                | Test-only override for the YAML modules map.                |
-
-## Emits
-
-| Event              | Payload                | When                                        |
-| ------------------ | ---------------------- | ------------------------------------------- |
-| `submit-success`   | `DcsFormSubmitSuccess` | API responded `2xx`.                        |
-| `submit-error`     | `DcsFormSubmitError`   | Network or non-2xx response after retries.  |
-| `validation-error` | `FormErrors`           | Submit attempted with invalid required/regex/etc. fields. |
-
-## Slots
-
-Every slot exposes scoped data so consumers (KT Braun, Kept) can swap
-shadcn primitives in without forking field components.
-
-| Slot       | Scope                                                              | Default                                              |
-| ---------- | ------------------------------------------------------------------ | ---------------------------------------------------- |
-| `header`   | `{ definition }`                                                   | `<h2>` + description                                 |
-| `progress` | `{ current, total, step }`                                         | `Step N of M — Title` (multi-step only)              |
-| `actions`  | `{ isFirstStep, isLastStep, submitting, prev, next }`              | Plain `<button>` elements                            |
-| `success`  | `{ definition }`                                                   | `definition.successMessage`                          |
-| `missing`  | `{ formId }`                                                       | Friendly fallback when the YAML can't be found      |
-
-Per-field components (`DcsFormText` etc.) expose `#input` slots so a
-shadcn site can replace the underlying primitive while keeping the
-wrapper, label, help, and error-message structure.
-
-## Composables
-
-For sites that want a fully custom layout, drop `<DcsForm/>` and use
-the underlying composables directly:
-
-```ts
-import {
-  useDcsForm,
-  validateForm,
-  submitFormValues,
-  parseFormYaml,
-} from '@duffcloudservices/site-forms'
-```
-
-- `useDcsForm({ definition })` — reactive `values`, `errors`, `steps`,
-  `next`, `prev`, `validateAll`, `collectSubmissionValues`, etc.
-- `validateForm(def, values, fieldIds?)` — pure validator usable in
-  any setting (server-side, tests, custom adapters).
-- `submitFormValues({ apiBase, siteSlug, payload })` — one-shot POST
-  with a single retry on 5xx and `multipart/form-data` when files are
-  present.
-
-## Visual editor integration
-
-The form root carries `data-form-key="<formId>"` and every field
-wrapper carries `data-form-field-key="<fieldId>"`. The portal preview
-iframe bridge uses these to highlight and select form regions. Do not
-strip them in custom layouts.
-
-## Schema validation
-
-In dev (`import.meta.env.DEV === true`) the runtime validates each
-loaded definition against the JSON Schema bundled in
-`src/schema/form-definition.schema.json` (snapshot of
-`contracts/dist/form-definition.schema.json`) and logs failures via
-`console.warn`. Production builds skip the warning to avoid noisy
-end-user consoles.
-
-When the contracts schema is regenerated (`pnpm --filter @dcs/contracts
-generate`), refresh the snapshot:
-
-```powershell
-Copy-Item ../../contracts/dist/form-definition.schema.json ./src/schema/form-definition.schema.json -Force
-pnpm --filter @duffcloudservices/site-forms test --run
-```
-
-## Scripts
-
-```powershell
-pnpm --filter @duffcloudservices/site-forms build       # vite library build (esm + dts)
-pnpm --filter @duffcloudservices/site-forms test        # vitest --run
-pnpm --filter @duffcloudservices/site-forms type-check  # vue-tsc --noEmit
-```
-
-## Related docs
-
-- **Authoring guide** — [`.docs/forms/AUTHORING.md`](../../.docs/forms/AUTHORING.md)
-  covers the YAML schema, worked examples, validation flow, HIPAA
-  guardrails, and the hand-coded → `<DcsForm/>` migration recipe.
-- **Publishing** — [`PUBLISHING.md`](./PUBLISHING.md) covers the
-  registry, OIDC trusted publishing, version bump policy, and the
-  exact dep line sibling customer-site repos should add.
-- **Validation CLI** — [`cli/forms/README.md`](../../cli/forms/README.md)
-  documents `dcs forms validate` and `dcs forms doctor`, which lint
-  the `.dcs/forms/*.yaml` files in a customer-site repo.
-
-## Ownership
-
-Per `packages/README.md`: external/consumer-facing docs live here, not
-in repo-root docs. Cross-cutting details (e.g. the public submissions
-API contract) belong in `contracts/README.md`.
+# @duffcloudservices/site-forms
+
+Shared `<DcsForm/>` runtime for DCS customer sites. Renders a managed
+form definition (created in the portal Form Manager) from a build-time
+`.dcs/forms/<formId>.yaml` snapshot, validates user input, and posts
+submissions to the public site-forms API.
+
+This is the single import surface for managed-form runtime code on
+customer sites — do not redefine field components per site.
+
+> **Inside the `dcs-again` workspace** the package is also reachable
+> as `@duffcloudservices/site-forms` via `workspace:*` (the workspace
+> name and the published name are the same).
+> **In sibling customer-site repos** install the published package
+> from public npm — see [`PUBLISHING.md`](./PUBLISHING.md) for the
+> consumption story and registry setup.
+
+## Install
+
+### In a workspace app (inside `dcs-again`)
+
+```jsonc
+// portal/package.json
+{
+  "dependencies": {
+    "@duffcloudservices/site-forms": "workspace:*"
+  }
+}
+```
+
+Then `pnpm install` from the repo root.
+
+### In a sibling customer-site repo (e.g. `ktbraunlaw`, `kept`)
+
+```powershell
+pnpm add @duffcloudservices/site-forms
+```
+
+See [`PUBLISHING.md`](./PUBLISHING.md) for the registry, version, and
+release-workflow details.
+
+## Vite setup
+
+Three pieces are required in the consuming site:
+
+1. **`vite-plugin-yaml`** so YAML modules return parsed objects:
+
+   ```ts
+   // vite.config.ts
+   import yaml from '@modyfi/vite-plugin-yaml'
+
+   export default defineConfig({
+     plugins: [vue(), yaml()],
+   })
+   ```
+
+   Without it, the loader falls back to parsing raw strings via
+   `js-yaml`, which works but pays the parse cost at boot.
+
+2. **A `formsModules` loader** in your site that does the
+   `import.meta.glob` from a path Vite can resolve (see below).
+
+3. **Env vars** the runtime reads:
+
+   | Variable                | Purpose                                              |
+   | ----------------------- | ---------------------------------------------------- |
+   | `VITE_DCS_PUBLIC_API`   | Base URL of the DCS public API (no trailing slash). |
+   | `VITE_DCS_SITE_SLUG`    | Default site slug used when the prop is omitted.    |
+
+### Why the `formsModules` prop is required in real sites
+
+`<DcsForm/>` ships with an internal `import.meta.glob('/.dcs/forms/*.yaml')`
+fallback, but Vite resolves the leading `/` against the **consumer's
+Vite project root** (the directory containing `vite.config.ts`).
+On every customer-site repo today, the `.dcs/forms/` directory lives
+at the **repo root**, one or more levels above the Vite root
+(typically `site/` or `docs/`). The internal glob therefore matches
+nothing and you get:
+
+```
+[@duffcloudservices/site-forms] No form definition found for "contact".
+Expected a YAML at /.dcs/forms/contact.yaml.
+```
+
+The fix is a one-file loader the rest of your site imports from.
+
+#### Vue SPA (`vite.config.ts` in `site/`)
+
+```ts
+// site/src/dcs-forms.ts
+const modules = import.meta.glob('../../.dcs/forms/*.yaml', {
+  eager: true,
+  import: 'default',
+})
+export const dcsFormsModules: Record<string, unknown> = modules
+```
+
+#### VitePress (`vite` block in `docs/.vitepress/config.ts`)
+
+```ts
+// docs/.vitepress/dcs-forms-loader.ts
+const modules = import.meta.glob('../../.dcs/forms/*.yaml', {
+  eager: true,
+  import: 'default',
+})
+export const dcsFormsModules: Record<string, unknown> = modules
+```
+
+The relative depth (`../../`) depends on where the loader file lives
+relative to the repo root. Adjust as needed.
+
+## Usage
+
+Place a YAML file at `<site>/.dcs/forms/contact.yaml`:
+
+```yaml
+formId: contact
+title: Contact Us
+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
+    required: true
+```
+
+Then in any page component:
+
+```vue
+<script setup lang="ts">
+import { DcsForm } from '@duffcloudservices/site-forms'
+import { dcsFormsModules } from '@/dcs-forms'
+</script>
+
+<template>
+  <DcsForm
+    form-id="contact"
+    :forms-modules="dcsFormsModules"
+    @submit-success="onSuccess"
+    @submit-error="onError"
+  />
+</template>
+```
+
+## Props
+
+| Prop                 | Type                              | Default                                | Notes                                                       |
+| -------------------- | --------------------------------- | -------------------------------------- | ----------------------------------------------------------- |
+| `formId`             | `string` (required)               | —                                      | Matches `.dcs/forms/<formId>.yaml`.                         |
+| `siteSlug`           | `string`                          | `import.meta.env.VITE_DCS_SITE_SLUG`   | Path segment in the submission URL.                         |
+| `definitionOverride` | `PortalFormDefinition`            | —                                      | Used by the portal preview iframe to show in-flight edits.  |
+| `apiBase`            | `string`                          | `import.meta.env.VITE_DCS_PUBLIC_API`  | Override for tests / non-prod environments.                 |
+| `captchaToken`       | `string`                          | —                                      | Attached to the submission payload when set.                |
+| `formsModules`       | `Record<string, unknown>`         | internal fallback glob (rarely matches) | **Required in real sites.** Pass a `Record<string, unknown>` from your own `import.meta.glob('../../.dcs/forms/*.yaml', { eager: true, import: 'default' })` — see Vite setup section. |
+
+## Emits
+
+| Event              | Payload                | When                                        |
+| ------------------ | ---------------------- | ------------------------------------------- |
+| `submit-success`   | `DcsFormSubmitSuccess` | API responded `2xx`.                        |
+| `submit-error`     | `DcsFormSubmitError`   | Network or non-2xx response after retries.  |
+| `validation-error` | `FormErrors`           | Submit attempted with invalid required/regex/etc. fields. |
+
+## Slots
+
+Every slot exposes scoped data so consumers (KT Braun, Kept) can swap
+shadcn primitives in without forking field components.
+
+| Slot       | Scope                                                              | Default                                              |
+| ---------- | ------------------------------------------------------------------ | ---------------------------------------------------- |
+| `header`   | `{ definition }`                                                   | `<h2>` + description                                 |
+| `progress` | `{ current, total, step }`                                         | `Step N of M — Title` (multi-step only)              |
+| `actions`  | `{ isFirstStep, isLastStep, submitting, prev, next }`              | Plain `<button>` elements                            |
+| `success`  | `{ definition }`                                                   | `definition.successMessage`                          |
+| `missing`  | `{ formId }`                                                       | Friendly fallback when the YAML can't be found      |
+
+Per-field components (`DcsFormText` etc.) expose `#input` slots so a
+shadcn site can replace the underlying primitive while keeping the
+wrapper, label, help, and error-message structure.
+
+## Composables
+
+For sites that want a fully custom layout, drop `<DcsForm/>` and use
+the underlying composables directly:
+
+```ts
+import {
+  useDcsForm,
+  validateForm,
+  submitFormValues,
+  parseFormYaml,
+} from '@duffcloudservices/site-forms'
+```
+
+- `useDcsForm({ definition })` — reactive `values`, `errors`, `steps`,
+  `next`, `prev`, `validateAll`, `collectSubmissionValues`, etc.
+- `validateForm(def, values, fieldIds?)` — pure validator usable in
+  any setting (server-side, tests, custom adapters).
+- `submitFormValues({ apiBase, siteSlug, payload })` — one-shot POST
+  with a single retry on 5xx and `multipart/form-data` when files are
+  present.
+
+## Visual editor integration
+
+The form root carries `data-form-key="<formId>"` and every field
+wrapper carries `data-form-field-key="<fieldId>"`. The portal preview
+iframe bridge uses these to highlight and select form regions. Do not
+strip them in custom layouts.
+
+## Schema validation
+
+In dev (`import.meta.env.DEV === true`) the runtime validates each
+loaded definition against the JSON Schema bundled in
+`src/schema/form-definition.schema.json` (snapshot of
+`contracts/dist/form-definition.schema.json`) and logs failures via
+`console.warn`. Production builds skip the warning to avoid noisy
+end-user consoles.
+
+When the contracts schema is regenerated (`pnpm --filter @dcs/contracts
+generate`), refresh the snapshot:
+
+```powershell
+Copy-Item ../../contracts/dist/form-definition.schema.json ./src/schema/form-definition.schema.json -Force
+pnpm --filter @duffcloudservices/site-forms test --run
+```
+
+## Scripts
+
+```powershell
+pnpm --filter @duffcloudservices/site-forms build       # vite library build (esm + dts)
+pnpm --filter @duffcloudservices/site-forms test        # vitest --run
+pnpm --filter @duffcloudservices/site-forms type-check  # vue-tsc --noEmit
+```
+
+## Related docs
+
+- **Authoring guide** — [`.docs/forms/AUTHORING.md`](../../.docs/forms/AUTHORING.md)
+  covers the YAML schema, worked examples, validation flow, HIPAA
+  guardrails, and the hand-coded → `<DcsForm/>` migration recipe.
+- **Publishing** — [`PUBLISHING.md`](./PUBLISHING.md) covers the
+  registry, OIDC trusted publishing, version bump policy, and the
+  exact dep line sibling customer-site repos should add.
+- **Validation CLI** — [`cli/forms/README.md`](../../cli/forms/README.md)
+  documents `dcs forms validate` and `dcs forms doctor`, which lint
+  the `.dcs/forms/*.yaml` files in a customer-site repo.
+
+## Ownership
+
+Per `packages/README.md`: external/consumer-facing docs live here, not
+in repo-root docs. Cross-cutting details (e.g. the public submissions
+API contract) belong in `contracts/README.md`.

package/dist/index.js

@@ -1,4 +1,4 @@
-import { reactive as X, ref as D, computed as p, defineComponent as I, createElementBlock as f, openBlock as l, normalizeClass as Z, renderSlot as S, createCommentVNode as k, createTextVNode as A, toDisplayString as b, createBlock as w, withCtx as V, createElementVNode as v, Fragment as T, renderList as B, watch as H, onMounted as ee, unref as u, resolveDynamicComponent as te } from "vue";
+import { reactive as X, ref as C, computed as p, defineComponent as I, createElementBlock as f, openBlock as l, normalizeClass as Z, renderSlot as S, createCommentVNode as k, createTextVNode as A, toDisplayString as b, createBlock as w, withCtx as V, createElementVNode as v, Fragment as T, renderList as B, watch as H, onMounted as ee, unref as u, resolveDynamicComponent as te } from "vue";
 import ie from "ajv";
 import re from "ajv-formats";
 import K from "js-yaml";
@@ -60,7 +60,7 @@ function _(e) {
   return t;
 }
 function ae(e) {
-  const { definition: t } = e, r = X(_(t)), i = D({}), o = D({}), d = D(!1), s = D(!1), c = D(null), a = D(0), n = p(() => t.fields), m = p(
+  const { definition: t } = e, r = X(_(t)), i = C({}), o = C({}), d = C(!1), s = C(!1), c = C(null), a = C(0), n = p(() => t.fields), m = p(
     () => t.steps && t.steps.length > 0 ? t.steps : null
   ), g = p(() => {
     const h = m.value;
@@ -79,7 +79,7 @@ function ae(e) {
   function y(h, F) {
     r[h] = F, i.value[h] && (i.value = { ...i.value, [h]: void 0 });
   }
-  function C(h) {
+  function D(h) {
     o.value = { ...o.value, [h]: !0 };
   }
   function $(h) {
@@ -134,7 +134,7 @@ function ae(e) {
     isLastStep: O,
     visibleFields: z,
     setValue: y,
-    touch: C,
+    touch: D,
     validateCurrentScope: L,
     validateAll: j,
     next: J,
@@ -270,7 +270,7 @@ const Ve = ["data-form-field-key"], we = ["for"], qe = {
 }, Pe = {
   key: 0,
   class: "dcs-form-field__help"
-}, Ce = {
+}, De = {
   key: 0,
   class: "dcs-form-field__error",
   role: "alert"
@@ -301,11 +301,11 @@ const Ve = ["data-form-field-key"], we = ["for"], qe = {
         e.field.helpText ? (l(), f("p", Pe, b(e.field.helpText), 1)) : k("", !0)
       ]),
       S(t.$slots, "error", {}, () => [
-        e.error ? (l(), f("p", Ce, b(e.error), 1)) : k("", !0)
+        e.error ? (l(), f("p", De, b(e.error), 1)) : k("", !0)
       ])
     ], 10, Ve));
   }
-}), De = ["id", "type", "name", "value", "placeholder", "required", "aria-invalid", "aria-describedby"], N = /* @__PURE__ */ I({
+}), Ce = ["id", "type", "name", "value", "placeholder", "required", "aria-invalid", "aria-describedby"], N = /* @__PURE__ */ I({
   __name: "DcsFormText",
   props: {
     field: {},
@@ -348,7 +348,7 @@ const Ve = ["data-form-field-key"], we = ["for"], qe = {
             "aria-describedby": e.error ? `${o.value}-error` : void 0,
             onInput: c[0] || (c[0] = (a) => i("update:modelValue", a.target.value)),
             onBlur: c[1] || (c[1] = (a) => i("blur"))
-          }, null, 40, De)
+          }, null, 40, Ce)
         ])
       ]),
       _: 3
@@ -772,7 +772,7 @@ const Ve = ["data-form-field-key"], we = ["for"], qe = {
           return N;
       }
     }
-    const O = D(null);
+    const O = C(null);
     async function z(y) {
       if (y.preventDefault(), !s.value) return;
       if (!n.validateAll()) {
@@ -801,9 +801,9 @@ const Ve = ["data-form-field-key"], we = ["for"], qe = {
     }
     return ee(() => {
       s.value || console.warn(
-        `[@duffcloudservices/site-forms] No form definition found for "${r.formId}". Expected a YAML at /.dcs/forms/${r.formId}.yaml.`
+        `[@duffcloudservices/site-forms] No form definition found for "${r.formId}". Expected a YAML at .dcs/forms/${r.formId}.yaml. In customer-site repos the YAML lives above the Vite root, so the internal auto-glob will not find it — pass formsModules explicitly: <DcsForm form-id="${r.formId}" :forms-modules="dcsFormsModules" />. See @duffcloudservices/site-forms README "Vite setup" section.`
       );
-    }), (y, C) => s.value ? u(n).submitted.value ? (l(), f("div", {
+    }), (y, D) => s.value ? u(n).submitted.value ? (l(), f("div", {
       key: 1,
       class: "dcs-form dcs-form--success",
       "data-form-key": e.formId
@@ -863,13 +863,13 @@ const Ve = ["data-form-field-key"], we = ["for"], qe = {
             key: 0,
             type: "button",
             class: "dcs-form__btn dcs-form__btn--prev",
-            onClick: C[0] || (C[0] = ($) => u(n).prev())
+            onClick: D[0] || (D[0] = ($) => u(n).prev())
           }, " Previous ")) : k("", !0),
           u(n).steps.value && !u(n).isLastStep.value ? (l(), f("button", {
             key: 1,
             type: "button",
             class: "dcs-form__btn dcs-form__btn--next",
-            onClick: C[1] || (C[1] = ($) => u(n).next())
+            onClick: D[1] || (D[1] = ($) => u(n).next())
           }, " Next ")) : k("", !0),
           !u(n).steps.value || u(n).isLastStep.value ? (l(), f("button", {
             key: 2,