@usgb/forms 1.0.1 → 1.0.3

package/README.md

@@ -2,47 +2,76 @@
 
 Shared lead and newsletter forms for the **PWA** (React) and **WordPress** (Web Component) hosts.
 
-You pick a predefined `formId`. The package owns fields, validation, consent copy, tracking keys, and layout. You own the submit endpoint, legal-document URLs, heading/subheading/CTA copy, and thank-you behavior.
+You pick a predefined `formId`. The package owns fields, validation, consent copy, and layout. You own the submit endpoint, legal-document URLs, heading/subheading/CTA copy, and thank-you behavior. The backend owns tracking and page-context collection.
 
 ## What you get
 
-| Artifact      | Path / export                                                   | Who uses it                         |
-| ------------- | --------------------------------------------------------------- | ----------------------------------- |
-| React package | `@usgb/forms` → `dist/index.js`                                 | PWA / any React host                |
-| Stylesheet    | `@usgb/forms/usgb-forms.css`                                    | **Required** for React hosts        |
-| Web Component | `dist/usgb-forms.js` (also versioned `usgb-forms.<version>.js`) | WordPress and other non-React hosts |
-| Catalog       | `@usgb/forms/manifest` → `forms-manifest.json`                  | CMS pickers, docs, tooling          |
+| Artifact      | Path / export                                                                                              | Who uses it                         |
+| ------------- | ---------------------------------------------------------------------------------------------------------- | ----------------------------------- |
+| React package | `@usgb/forms` → `dist/index.js`                                                                            | PWA / any React host                |
+| Stylesheet    | `@usgb/forms/usgb-forms.css`                                                                               | **Required** for React hosts        |
+| Web Component | `dist/usgb-forms.js` (also versioned `usgb-forms.<version>.js`)                                            | WordPress and other non-React hosts |
+| Catalog       | `@usgb/forms/manifest` → `forms-manifest.json` (also versioned `forms-manifest.<version>.json` in `dist/`) | CMS pickers, Gutenberg, tooling     |
 
 The Web Component script injects the same CSS once on load. React hosts must import the stylesheet themselves.
 
 ## Mental model
 
-| You pass                         | Package already decided                                                               |
-| -------------------------------- | ------------------------------------------------------------------------------------- |
-| `formId`                         | Fields, required/optional rules, consent bundle, tracking set, layout family (`kind`) |
-| `adapter.submit`                 | Where the payload goes (never an attribute or hardcoded URL)                          |
-| `legalUrls` / `*-url`            | Hrefs for package-owned consent copy                                                  |
-| `heading`, `subheading`, `ctaLabel` | Marketing copy around the form                                                     |
-| `successMessage` or `successUrl` | Thank-you UX after accept                                                             |
+| You pass                            | Package already decided                                               |
+| ----------------------------------- | --------------------------------------------------------------------- |
+| `formId`                            | Fields, required/optional rules, consent pins, layout family (`kind`) |
+| `adapter.submit`                    | Where the payload goes (never an attribute or hardcoded URL)          |
+| `legalUrls` / `*-url`               | Hrefs for package-owned consent copy                                  |
+| `heading`, `subheading`, `ctaLabel` | Marketing copy around the form                                        |
+| `successMessage` or `successUrl`    | Thank-you UX after accept                                             |
 
-Hosts **must not** invent field lists, consent wording, or tracking keys. New forms are new catalog entries in this package, not host-built schemas.
+Hosts **must not** invent field lists or consent wording. New forms are new catalog entries in this package, not host-built schemas.
 
-Use `listFormDefinitions()` (or the manifest) when a CMS needs a picker of available `formId`s. Deeper catalog rules: [`src/definitions/context.md`](src/definitions/context.md).
+Use `listFormDefinitions()` (or the manifest) when a CMS needs a picker of available `formId`s, and `listEditorOptions(formId)` for the settings that picker may expose (see [Editor options](#editor-options)).
 
 ## Available forms
 
-| `formId`             | Kind         | Fields                                                    | Consent                        | Variants                                                |
-| -------------------- | ------------ | --------------------------------------------------------- | ------------------------------ | ------------------------------------------------------- |
-| `main-investors-kit` | `lead`       | First name, last name, email (required); phone (optional) | TCPA checkbox (`lead-tcpa` v1) | `dense`, `large`, `sidebar`, plus optional `two-column` |
-| `newsletter`         | `newsletter` | Email only                                                | None                           | None — omit `variants` / `variant`                      |
+| `formId`                    | Kind         | Fields                                                    | Consent                                                         | Size/layout                                                  |
+| --------------------------- | ------------ | --------------------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------ |
+| `magento-fik`               | `lead`       | First name, last name, email (required); phone (optional) | Optional TCPA (v1), marketing SMS, and terms/privacy checkboxes | `dense`, `large`, or `sidebar`; optional two-column name row |
+| `magento-ira-kick-article`  | `lead`       | First name, last name, email, phone (all required)        | Optional TCPA checkbox (v2, links terms and privacy)            | `dense`, `large`, or `sidebar`; optional two-column name row |
+| `magento-fik-blog-rail`     | `lead`       | First name, last name, email, phone (all required)        | Optional TCPA checkbox (v2, links terms and privacy)            | `dense`, `large`, or `sidebar`; optional two-column name row |
+| `main-investors-kit-notice` | `lead`       | Same as `magento-fik`                                     | Clickwrap notice only (`lead-clickwrap` v2)                     | `dense`, `large`, or `sidebar`; optional two-column name row |
+| `newsletter`                | `newsletter` | Email only                                                | None                                                            | None — omit `variant` and `twoColumn` / `two-column`         |
 
-Appearances for both: `on-light` | `on-dark`. Appearance only recolors the form for readability on a light or dark host background — it never sets a background, padding, or radius. The host container owns those.
+Appearances for every catalog form: `on-light` | `on-dark`. Appearance only recolors the form for readability on a light or dark host background — it never sets a background, padding, or radius. The host container owns those.
 
 `kind` is the layout family (lead grid vs inline newsletter row). The root exposes `data-kind` for CSS. Several catalog forms can share one kind (e.g. another lead kit that reuses the lead layout).
 
-## Install
+### Editor options
+
+`editorOptions` in the manifest lists every host-owned setting an editor may apply, and each form's `editor.options` lists the ones that form accepts. A CMS panel should build its controls from those two lists instead of hardcoding prop names:
+
+| Option           | Control   | React prop       | Attribute                                | Applies to                                       |
+| ---------------- | --------- | ---------------- | ---------------------------------------- | ------------------------------------------------ |
+| `appearance`     | select    | `appearance`     | `appearance`                             | All forms — values in `supportedAppearances`     |
+| `variant`        | select    | `variant`        | `variant`                                | Lead forms — values in `supportedVariants`       |
+| `twoColumn`      | checkbox  | `twoColumn`      | `two-column`                             | Lead forms — independent of the size variant     |
+| `heading`        | text      | `heading`        | `heading`                                | All forms                                        |
+| `subheading`     | text      | `subheading`     | `subheading`                             | All forms                                        |
+| `ctaLabel`       | text      | `ctaLabel`       | `cta`                                    | All forms — default is the form's `ctaLabel`     |
+| `legalUrls`      | url group | `legalUrls`      | `*-url` (see `attributes` on the option) | Forms with consent — keys in `requiredLegalUrls` |
+| `successMessage` | text      | `successMessage` | `success-message`                        | All forms                                        |
+| `successUrl`     | url       | `successUrl`     | `success-url`                            | All forms                                        |
+
+Only `legalUrls` is required, and only for the keys a form's consents name — the form does not render when one is missing. Everything else is optional.
 
-Registry package name, scope, and CDN base URL are **TBD** — examples below use the working package name `@usgb/forms` and a placeholder CDN host. Replace them when publishing is finalized.
+`listEditorOptions(formId)` returns those options already resolved for one form (allowed values, effective default, React prop, and attribute), so a Gutenberg panel does not have to follow the `valuesFrom` / `defaultFrom` pointers itself:
+
+```ts
+import { listEditorOptions } from '@usgb/forms'
+
+listEditorOptions('newsletter')
+// [{ key: 'appearance', control: 'select', values: ['on-light', 'on-dark'], defaultValue: 'on-light', … }, …]
+// `variant`, `twoColumn`, and `legalUrls` are absent — newsletter takes none.
+```
+
+## Install
 
 ### npm (React / PWA)
 
@@ -63,15 +92,13 @@ Peer dependency: `react` and `react-dom` `^18` or `^19`.
 
 ### CDN (Web Component / WordPress)
 
-Load the built IIFE (styles inject themselves):
+Load the built script for a release (styles inject themselves):
 
 ```html
-<script src="https://cdn.example.com/usgb-forms/usgb-forms.1.0.0.js"></script>
+<script src="https://forms.usgoldbureau.com/usgb-forms.1.0.3.js"></script>
 ```
 
-Exact CDN hostname, path, and versioning scheme are **TBD**. Prefer a versioned filename (`usgb-forms.<version>.js`) so hosts can pin releases.
-
-Until the package is published, you can still develop against a local checkout (`yarn add file:../usgb-forms` or `yarn link`).
+Pin the script and the catalog together: `usgb-forms.<version>.js` and `forms-manifest.<version>.json` on `https://forms.usgoldbureau.com/`. Gutenberg should load that matching manifest when listing `formId`s.
 
 ## React (PWA)
 
@@ -79,14 +106,13 @@ Until the package is published, you can still develop against a local checkout (
 import { UsgbForm, createStubAdapter, PWA_LEGAL_URLS } from '@usgb/forms'
 import '@usgb/forms/usgb-forms.css'
 ;<UsgbForm
-    formId="main-investors-kit"
+    formId="magento-fik"
     appearance="on-dark"
-    variants={['large', 'two-column']}
+    variant="large"
+    twoColumn
     heading="Get My Free Guide"
     subheading="Enter your details to receive the Main Investors Kit."
     ctaLabel="GET MY FREE GUIDE"
-    source="cms-home"
-    campaign="spring-kit"
     legalUrls={PWA_LEGAL_URLS}
     successMessage="Thanks — we will send your kit shortly."
     adapter={yourHostAdapter}
@@ -99,7 +125,7 @@ import '@usgb/forms/usgb-forms.css'
 />
 ```
 
-Newsletter (no consent, no variants):
+Newsletter (no consent or lead layout options):
 
 ```tsx
 <UsgbForm
@@ -113,42 +139,51 @@ Newsletter (no consent, no variants):
 
 ### React props
 
-| Prop                      | Required                   | Role                                                                                                |
-| ------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------- |
-| `formId`                  | yes                        | Catalog key (`main-investors-kit`, `newsletter`, …)                                                 |
-| `adapter`                 | yes                        | `HostAdapter` with `host`, `getTrackingHints()`, `submit()`                                         |
-| `appearance`              | no                         | `on-light` (default) or `on-dark`                                                                   |
-| `variants`                | no                         | Lead only. Default `['dense']`. One of `dense` \| `large` \| `sidebar`, optionally add `two-column` |
-| `heading` / `subheading`  | no                         | Title and supporting copy                                                                           |
-| `ctaLabel`                | no                         | Submit button label. Falls back to the catalog `ctaLabel` for that `formId`                         |
-| `source` / `campaign`     | no                         | Placement / campaign context in the payload                                                         |
-| `legalUrls`               | when consent requires them | Host CMS paths for legal links in consent copy                                                      |
-| `successMessage`          | no                         | Inline thank-you when `successUrl` is omitted                                                       |
-| `successUrl`              | no                         | Redirect after accept (analytics / `onAccepted` are invoked first; see Success behavior)            |
-| `analytics`               | no                         | `(event) => void` for view / validation / submit / success / failure                                |
-| `className`               | no                         | Extra class on `.usgb-form`                                                                         |
-| `onAccepted` / `onFailed` | no                         | Callbacks with the submission payload                                                               |
+| Prop                      | Required                   | Role                                                                                                                                                              |
+| ------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `formId`                  | yes                        | Catalog key (`magento-fik`, `newsletter`, …)                                                                                                                      |
+| `adapter`                 | yes                        | `HostAdapter` with `host` and `submit()`                                                                                                                          |
+| `appearance`              | no                         | `on-light` (default) or `on-dark`                                                                                                                                 |
+| `variant`                 | no                         | Lead only. Default `dense`. Exactly one of `dense` \| `large` \| `sidebar`                                                                                        |
+| `twoColumn`               | no                         | Lead only. Places grouped name fields in two columns when space allows                                                                                            |
+| `heading` / `subheading`  | no                         | Title and supporting copy                                                                                                                                         |
+| `ctaLabel`                | no                         | Submit button label. Falls back to the catalog `ctaLabel` for that `formId`                                                                                       |
+| `legalUrls`               | when consent requires them | Host CMS paths. Keys: `clientAgreement`, `privacyPolicy`, `userAgreement`, `marketLossPolicy`, `electronicDisclaimer`, `termsOfSale` (see Consent and legal URLs) |
+| `successMessage`          | no                         | Inline thank-you when `successUrl` is omitted                                                                                                                     |
+| `successUrl`              | no                         | Redirect after accept (analytics / `onAccepted` are invoked first; see Success behavior)                                                                          |
+| `analytics`               | no                         | `(event) => void`. Event `type`: `view` \| `validation_failure` \| `submit_attempt` \| `success` \| `failure`. React-only — the Web Component has no equivalent   |
+| `className`               | no                         | Extra class on `.usgb-form`. React-only — put classes on the host page around `<usgb-form>`                                                                       |
+| `onAccepted` / `onFailed` | no                         | Callbacks with the submission payload. Web Component: `usgb-form:success` / `usgb-form:failure`                                                                   |
 
 ## Web Component (WordPress)
 
 Load one script. Styles are injected automatically.
 
-````html
-<script src="https://cdn.example.com/usgb-forms/usgb-forms.1.0.0.js"></script>
+```html
+<script src="https://forms.usgoldbureau.com/usgb-forms.1.0.3.js"></script>
 <usgb-form
-    ```
-    form-id="main-investors-kit"
+    form-id="magento-fik"
     appearance="on-dark"
-    variant="large two-column"
+    variant="large"
+    two-column
     heading="Get My Free Guide"
     subheading="Enter your details to receive the Main Investors Kit."
     cta="GET MY FREE GUIDE"
-    source="cms-home"
-    client-agreement-url="/client-agreement/"
+    user-agreement-url="/user-agreement/"
     privacy-policy-url="/privacy-policy/"
     success-message="Thanks — we will send your kit shortly."
 ></usgb-form>
-````
+```
+
+Clickwrap kit (`main-investors-kit-notice`) needs the two notice URLs:
+
+```html
+<usgb-form
+    form-id="main-investors-kit-notice"
+    privacy-policy-url="/privacy-policy/"
+    user-agreement-url="/user-agreement/"
+></usgb-form>
+```
 
 Submit is **not** an attribute. Markup alone uses a stub adapter. Assign a real `HostAdapter` in script:
 
@@ -157,10 +192,6 @@ Submit is **not** an attribute. Markup alone uses a stub adapter. Assign a real
     const el = document.querySelector('usgb-form')
     el.adapter = {
         host: 'wordpress',
-        getTrackingHints() {
-            // Cookies, UTMs, click ids — keys must match the package tracking registry
-            return {}
-        },
         async submit(payload) {
             const res = await fetch('/your-form-submit', {
                 method: 'POST',
@@ -183,48 +214,71 @@ Submit is **not** an attribute. Markup alone uses a stub adapter. Assign a real
 
 ### Attribute map
 
-| Attribute                                       | React prop                                                    |
-| ----------------------------------------------- | ------------------------------------------------------------- |
-| `form-id`                                       | `formId`                                                      |
-| `appearance`                                    | `appearance`                                                  |
-| `variant`                                       | `variants` (space-separated)                                  |
-| `heading` / `subheading`                        | `heading` / `subheading`                                      |
-| `cta`                                           | `ctaLabel`                                                    |
-| `source` / `campaign`                           | `source` / `campaign`                                         |
-| `success-message` / `success-url`               | `successMessage` / `successUrl`                               |
-| `client-agreement-url`, `privacy-policy-url`, … | `legalUrls.*`                                                 |
-| `host`                                          | Used only for the stub adapter before you assign `el.adapter` |
+`form-id` defaults to `magento-fik`, `appearance` to `on-light`, `variant` to `dense`, and `host` to `wordpress`. `two-column` is a boolean attribute and is off when omitted. There is no `version` attribute — `definitionVersion` comes from the catalog.
+
+| Attribute                   | React prop                                                    |
+| --------------------------- | ------------------------------------------------------------- |
+| `form-id`                   | `formId`                                                      |
+| `appearance`                | `appearance`                                                  |
+| `variant`                   | `variant`                                                     |
+| `two-column`                | `twoColumn`                                                   |
+| `heading` / `subheading`    | `heading` / `subheading`                                      |
+| `cta`                       | `ctaLabel`                                                    |
+| `success-message`           | `successMessage`                                              |
+| `success-url`               | `successUrl`                                                  |
+| `client-agreement-url`      | `legalUrls.clientAgreement`                                   |
+| `privacy-policy-url`        | `legalUrls.privacyPolicy`                                     |
+| `user-agreement-url`        | `legalUrls.userAgreement`                                     |
+| `market-loss-policy-url`    | `legalUrls.marketLossPolicy`                                  |
+| `electronic-disclaimer-url` | `legalUrls.electronicDisclaimer`                              |
+| `terms-of-sale-url`         | `legalUrls.termsOfSale`                                       |
+| `host`                      | Used only for the stub adapter before you assign `el.adapter` |
+
+Same names are exported as `LEGAL_URL_ATTRS` (`legalUrls` key → attribute). Gutenberg and other generators should use that map instead of hard-coding strings.
+
+### Properties and events
+
+| Surface             | Role                                                                                    |
+| ------------------- | --------------------------------------------------------------------------------------- |
+| `el.adapter`        | Assign a `HostAdapter`. Not an attribute. Markup without this uses `createStubAdapter`. |
+| `usgb-form:success` | `e.detail` is `SubmissionPayload` (same as React `onAccepted`)                          |
+| `usgb-form:failure` | `e.detail` is `{ payload, message }` (same as React `onFailed`)                         |
+
+The Web Component does not expose `analytics` or `className`. Listen for the events above, or wrap the element for layout.
 
 ## Host adapter
 
 ```ts
 interface HostAdapter {
     host: 'pwa' | 'wordpress'
-    getTrackingHints(): Partial<Record<TrackingKey, string | undefined>>
     submit(payload: SubmissionPayload): Promise<SubmitResult>
 }
 ```
 
 -   `submit` must return `{ status: 'accepted' }` or `{ status: 'failed', message?: string }`.
--   The package never embeds Workato, Magento, or WordPress endpoints.
--   `createStubAdapter('pwa' | 'wordpress')` accepts every payload (playground / markup-only WC).
--   Tracking keys and destination names live in `forms-manifest.json`. Hosts may supply values for registered keys; they must not invent new ones.
+-   The package does not choose a submit URL.
+-   `createStubAdapter('pwa' | 'wordpress')` accepts every payload (markup-only Web Component).
+-   Tracking, UTMs, page URL, referrer, and similar context are collected by the backend. This package does not send a `context` object.
 
 ### Payload shape (summary)
 
-Successful submits send a nested envelope: `formId`, `definitionVersion`, `submissionContractVersion`, `idempotencyKey`, `data` (field values), optional `consent`, and `context` (`host`, `source`, `campaign`, `page`, `tracking`). Exact field and tracking sets come from the form’s catalog entry.
+Successful submits send `formId`, `definitionVersion`, `submissionContractVersion`, `idempotencyKey`, `data` (field values), and optional `consents` (grant booleans, opt-in dates, and `*_consent_language` strings). Exact field sets come from the form’s catalog entry.
 
 ## Consent and legal URLs
 
-Consent bundles are versioned and package-owned (checkboxes and/or clickwrap notices). Hosts only supply document **hrefs**.
-
--   `main-investors-kit` uses `lead-tcpa` v1 and requires `clientAgreement` and `privacyPolicy`.
--   PWA Magento defaults: `PWA_LEGAL_URLS` → `/content/client-agreement`, `/content/privacy-policy`.
--   WordPress must pass every URL required by the selected consent. A consent form with a missing required URL **does not render**.
--   Checkbox values land in `consent.values` (and mirrored in `data`). Notices have no boolean field; the payload still records consent definition id/version.
--   Distinct legal wording requires a new consent id/version in this package — not freeform copy from the host.
+Consent policies are versioned and package-owned (checkboxes and/or clickwrap notices). Forms list zero or more pins (`definitionId` + `definitionVersion` + optional `required` for checkboxes). Hosts only supply document **hrefs**.
 
-`LEAD_CLICKWRAP_V1` (“By clicking the button…”) is in the catalog and needs five legal URLs (`privacyPolicy`, `userAgreement`, `marketLossPolicy`, `electronicDisclaimer`, `termsOfSale`). It is not attached to a `formId` until that recipe is chosen.
+-   `magento-fik` pins `lead-tcpa`, `lead-sms`, and `lead-tospp` (all v1, optional checkboxes). Required URLs: `userAgreement`, `privacyPolicy` (`user-agreement-url`, `privacy-policy-url`).
+-   `magento-ira-kick-article` and `magento-fik-blog-rail` pin `lead-tcpa` v2 only (optional checkbox). Unlike v1, v2 links the terms and privacy policy, so required URLs: `userAgreement`, `privacyPolicy`.
+-   `main-investors-kit-notice` pins `lead-clickwrap` v2 (notice only: Privacy Policy, Terms & Conditions, and text/call consent). Required URLs: `privacyPolicy`, `userAgreement`. It shares the v1 payload key `clickwrap_consent_language`. `lead-clickwrap` v1 (five document links) stays in the catalog and is not pinned.
+-   `newsletter` has no consents and needs no legal URLs.
+-   `LEGAL_URL_ATTRS` lists every host-owned slot, including `clientAgreement` / `client-agreement-url`. No current catalog consent requires `clientAgreement`; it is still valid on `legalUrls` / the attribute (PWA Magento ships it in `PWA_LEGAL_URLS`).
+-   PWA Magento defaults (`PWA_LEGAL_URLS`): `/content/client-agreement`, `/content/privacy-policy`, `/content/user-agreement`, `/content/market-loss-policy`, `/content/electronic-disclaimer`, `/content/terms-of-sale`.
+-   WordPress must pass every URL required by the selected consents. A form with a missing required URL **does not render**. CMS pickers can compute the list with `getFormDefinition`, `resolveFormConsents`, and `collectRequiredLegalUrls`, then map keys through `LEGAL_URL_ATTRS`.
+-   `isCompleteLegalUrls(legalUrls, requiredKeys)` is the same check the renderer uses.
+-   Checkbox grants land in `consents` only (`tcpa_form_consent_granted`, `sms_form_consent_granted`, `tospp_form_consent_granted`). The exact copy shown is `tcpa_consent_language` (and the matching keys for other policies), even when unchecked.
+-   Checking the TCPA box also adds `tcpa_form_opt_in_date` (YYYY-MM-DD). The notice form only sends `clickwrap_consent_language`.
+-   Hosts supply document hrefs only. Consent wording stays in this package.
 
 ## Success behavior
 
@@ -280,25 +334,6 @@ Appearance never paints a card. Put the form on a dark host surface and pass `ap
 
 ```html
 <div style="background: #001f3d; padding: 2rem; border-radius: 0.75rem">
-    <usgb-form form-id="main-investors-kit" appearance="on-dark" …></usgb-form>
+    <usgb-form form-id="magento-fik" appearance="on-dark" …></usgb-form>
 </div>
 ```
-
-Visual styles are a ported snapshot of the PWA form kit. When PWA form styles change, update this package and bump the version.
-
-## Develop (package maintainers)
-
-```bash
-yarn install
-yarn dev      # Vite playground (tries :5174)
-yarn build
-yarn typecheck
-yarn lint
-yarn format
-```
-
-Prettier and ESLint match magento-frontend (4-space indent, single quotes, no semicolons, print width 80).
-
-## Git
-
-Local repo only. Connect a GitHub remote later when ready to publish.