@usgb/forms 1.0.0 → 1.0.1

package/README.md

@@ -2,7 +2,7 @@
 
 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/CTA copy, and thank-you behavior.
+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.
 
 ## What you get
 
@@ -22,7 +22,7 @@ The Web Component script injects the same CSS once on load. React hosts must imp
 | `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`, `body`, `ctaLabel`    | Marketing copy around the form                                                        |
+| `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.
@@ -36,7 +36,7 @@ Use `listFormDefinitions()` (or the manifest) when a CMS needs a picker of avail
 | `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`                      |
 
-Appearances for both: `light` | `navy`.
+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.
 
 `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).
 
@@ -80,10 +80,10 @@ import { UsgbForm, createStubAdapter, PWA_LEGAL_URLS } from '@usgb/forms'
 import '@usgb/forms/usgb-forms.css'
 ;<UsgbForm
     formId="main-investors-kit"
-    appearance="navy"
+    appearance="on-dark"
     variants={['large', 'two-column']}
     heading="Get My Free Guide"
-    body="Enter your details to receive the Main Investors Kit."
+    subheading="Enter your details to receive the Main Investors Kit."
     ctaLabel="GET MY FREE GUIDE"
     source="cms-home"
     campaign="spring-kit"
@@ -104,7 +104,7 @@ Newsletter (no consent, no variants):
 ```tsx
 <UsgbForm
     formId="newsletter"
-    appearance="light"
+    appearance="on-light"
     heading="Subscribe"
     ctaLabel="SUBSCRIBE"
     adapter={yourHostAdapter}
@@ -117,10 +117,10 @@ Newsletter (no consent, no variants):
 | ------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------- |
 | `formId`                  | yes                        | Catalog key (`main-investors-kit`, `newsletter`, …)                                                 |
 | `adapter`                 | yes                        | `HostAdapter` with `host`, `getTrackingHints()`, `submit()`                                         |
-| `appearance`              | no                         | `light` (default) or `navy`                                                                         |
+| `appearance`              | no                         | `on-light` (default) or `on-dark`                                                                   |
 | `variants`                | no                         | Lead only. Default `['dense']`. One of `dense` \| `large` \| `sidebar`, optionally add `two-column` |
-| `heading` / `body`        | no                         | Title and supporting copy                                                                           |
-| `ctaLabel`                | no                         | Submit button label                                                                                 |
+| `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                                                       |
@@ -138,9 +138,10 @@ Load one script. Styles are injected automatically.
 <usgb-form
     ```
     form-id="main-investors-kit"
-    appearance="navy"
+    appearance="on-dark"
     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/"
@@ -187,7 +188,7 @@ Submit is **not** an attribute. Markup alone uses a stub adapter. Assign a real
 | `form-id`                                       | `formId`                                                      |
 | `appearance`                                    | `appearance`                                                  |
 | `variant`                                       | `variants` (space-separated)                                  |
-| `heading` / `body`                              | `heading` / `body`                                            |
+| `heading` / `subheading`                        | `heading` / `subheading`                                      |
 | `cta`                                           | `ctaLabel`                                                    |
 | `source` / `campaign`                           | `source` / `campaign`                                         |
 | `success-message` / `success-url`               | `successMessage` / `successUrl`                               |
@@ -240,10 +241,10 @@ This package does **not** wait on a returned Promise, add a flush timeout, or ca
 
 What is reliable today:
 
-- Inline thank-you (`successMessage` only) — no navigation, so tags usually complete.
-- Same-document hash redirects (`#thank-you`) — no unload.
-- Host `analytics` that uses `navigator.sendBeacon` or `fetch(..., { keepalive: true })`.
-- Conversion measured on the thank-you page itself, not on this `success` event.
+-   Inline thank-you (`successMessage` only) — no navigation, so tags usually complete.
+-   Same-document hash redirects (`#thank-you`) — no unload.
+-   Host `analytics` that uses `navigator.sendBeacon` or `fetch(..., { keepalive: true })`.
+-   Conversion measured on the thank-you page itself, not on this `success` event.
 
 `submit_attempt` is safer than `success` because it fires before `adapter.submit` and has the round-trip to flush. Prefer the thank-you page (or a beacon) when `successUrl` is a full navigation.
 
@@ -264,16 +265,24 @@ Prefer **custom properties** on `.usgb-form` for color, type, and spacing:
     --usgb-field-border: #cccccc;
 }
 
-.usgb-form[data-appearance='navy'] {
+.usgb-form[data-appearance='on-dark'] {
     --usgb-button-background: #f4e08e;
 }
 ```
 
 Use class selectors when a token does not exist (`.usgb-form .usgb-btn { border-radius: 0; }`).
 
-Stable hooks: `.usgb-form` (`data-appearance`, `data-variant`, `data-kind`), `.usgb-form-heading`, `.usgb-form-body`, `.usgb-form-grid`, `.usgb-form-inline`, `.usgb-field-control`, `.usgb-field-error`, `.usgb-consent-*`, `.usgb-btn`, `.usgb-form-status-*`.
+Stable hooks: `.usgb-form` (`data-appearance`, `data-variant`, `data-kind`), `.usgb-form-heading`, `.usgb-form-subheading`, `.usgb-form-grid`, `.usgb-form-inline`, `.usgb-field-control`, `.usgb-field-error`, `.usgb-consent-*`, `.usgb-btn`, `.usgb-form-status-*`.
 
-Semantic tokens (`--usgb-form-surface`, `--usgb-field-*`, `--usgb-button-*`, `--usgb-newsletter-underline`, …) are the first place to retheme. Palette vars (`--usgb-blue-1`, …) are a PWA snapshot. Error and checkbox glyphs are inline SVGs that use `currentColor` — override `--usgb-alert-danger` or `--usgb-checkbox-mark` to recolor them.
+Semantic tokens (`--usgb-field-*`, `--usgb-button-*`, `--usgb-newsletter-underline`, …) are the first place to retheme. Palette vars (`--usgb-blue-1`, …) are a PWA snapshot. Error and checkbox glyphs are inline SVGs that use `currentColor` — override `--usgb-alert-danger` or `--usgb-checkbox-mark` to recolor them.
+
+Appearance never paints a card. Put the form on a dark host surface and pass `appearance="on-dark"` (or `on-light` on a light surface):
+
+```html
+<div style="background: #001f3d; padding: 2rem; border-radius: 0.75rem">
+    <usgb-form form-id="main-investors-kit" 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.
 

package/dist/forms-manifest.json

@@ -186,6 +186,7 @@
                 "user_agent",
                 "ip_address"
             ],
+            "ctaLabel": "GET MY FREE GUIDE",
             "consent": {
                 "definitionId": "lead-tcpa",
                 "definitionVersion": "1",
@@ -200,7 +201,7 @@
                 "description": "Standard lead form: name, email, phone, TCPA consent. Use on full-width landing pages and PWA kit/sidebar placements.",
                 "whenToUse": "Default kit request. Do not use for affiliate landers or IRA-specific leads.",
                 "whenNotToUse": "Affiliate pages (separate definition). IRA kit (separate definition when added).",
-                "supportedAppearances": ["light", "navy"],
+                "supportedAppearances": ["on-light", "on-dark"],
                 "supportedVariants": ["dense", "large", "sidebar", "two-column"]
             }
         },
@@ -220,12 +221,13 @@
                 "utm_term",
                 "utm_content"
             ],
+            "ctaLabel": "SUBSCRIBE",
             "editor": {
                 "label": "Newsletter",
                 "description": "Email-only newsletter signup. No TCPA consent.",
                 "whenToUse": "Footer or landing newsletter capture where only an email is required.",
                 "whenNotToUse": "Lead kits that need name, phone, or TCPA consent.",
-                "supportedAppearances": ["light", "navy"],
+                "supportedAppearances": ["on-light", "on-dark"],
                 "supportedVariants": []
             }
         }