@duffcloudservices/site-forms 0.1.1 → 0.1.2

package/README.md

@@ -1,260 +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
-
-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`.
+# @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`.