=== FormVue — Lead Capture ===
Contributors: formvue
Tags: lead capture, contact form, video, phone, popup
Requires at least: 5.8
Tested up to: 6.8
Requires PHP: 7.4
Stable tag: 2.4.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Add FormVue lead capture widgets — inline button, modal, contact, or content — via Gutenberg, Elementor, or shortcodes.

== Description ==

FormVue lets you add lead capture widgets to any page on your WordPress site. There are four independent widgets — pick the one you need and configure only its options:

* **Inline button** — a button that transforms into a phone number input.
* **Modal** — a trigger button that opens the form in a popup.
* **Contact** — an embedded contact form rendered directly on the page.
* **Content** — a coupon-gated content flow.

After a visitor submits, they receive an SMS with a personalized link to your FormVue video form.

You need a free FormVue account at [formvue.com](https://formvue.com/) to obtain a Form ID.

**Features:**

* Four independent widgets — inline button, modal, contact form, content (coupon) — each with only its relevant options
* Works with Gutenberg, Elementor, Divi 5 (native modules), and any builder that accepts shortcodes (WPBakery, Beaver Builder, etc.)
* Shortcodes: `[fvlc_inline]`, `[fvlc_modal]`, `[fvlc_contact]`, `[fvlc_content]`
* Four native Gutenberg blocks, each with a live visual preview
* Four Elementor widgets with drag & drop
* Global default settings in WP Admin
* Customizable colors, sizes, variants, and borders
* Campaign / UTM attribution and query-param passthrough
* Mobile-friendly (renders as a link on mobile devices)
* The widget runtime is bundled inside the plugin — no external script loader

== External services ==

This plugin connects to the FormVue service (operated by FormVue) to capture and process leads. This connection is required for the plugin's core functionality — without it, submitted forms cannot be delivered.

What is sent, and when:

* When a widget is shown, an impression event and, on interaction, a click event are sent to `https://formvue.com` (proxied to FormVue's API). Each event includes the configured Form ID, optional campaign/UTM attribution, the page URL, page title, referrer, and screen width.
* When query-param passthrough is on, these same two events also carry the query parameters from the page URL. They are sent when the widget renders, before the visitor submits anything.
* The Extra Params you set on the widget or on the settings page are sent only with the submission and in the form link, as prefilled answers. They are not sent with impression or click events. Do not put personal or confidential values in the Extra Params field.
* When a visitor submits the form (e.g. a phone number or contact fields), those values are sent to `https://formvue.com` to create a lead and trigger the SMS/email with the personalized form link.
* The widget logo image is loaded from `https://api.formvue.com`.
* When a form has an address question, the address the visitor types is sent to `https://formvue.com` as they type, to suggest matching street addresses. FormVue looks the address up with Mapbox, so the typed text is passed on to Mapbox to find the suggestions. If the visitor picks a suggestion, its street, city, state, and ZIP are submitted with the lead.
* When the form requires a verified address (set per form in FormVue), the address is checked with the US Postal Service when the visitor submits: its street, unit, city, state, and ZIP are sent to `https://formvue.com`, which verifies them with Lob (a USPS address-verification provider). The outcome is submitted with the lead. Forms that do not require a verified address send nothing for this.

No data is sent until a widget actually renders on a page. The plugin itself loads no JavaScript from any third-party server — the widget runtime ships inside the plugin.

* FormVue terms of service: https://formvue.com/legals/terms-of-service
* FormVue privacy policy: https://formvue.com/legals/privacy
* Mapbox terms of service: https://www.mapbox.com/legal/tos
* Mapbox privacy policy: https://www.mapbox.com/legal/privacy
* Lob terms of service: https://www.lob.com/terms
* Lob privacy policy: https://www.lob.com/privacy

== Third-party libraries ==

The widget runtime bundled in `build/sdk/` is compiled from the open-source FormVue Embed SDK and includes the following libraries, all under the MIT license (GPL-compatible):

* Preact and @preact/signals — https://preactjs.com (MIT)
* @formisch/preact — https://github.com/fabian-hiller/formisch (MIT)
* valibot — https://valibot.dev (MIT)
* openapi-fetch — https://github.com/openapi-ts/openapi-typescript (MIT)
* Tailwind CSS — https://tailwindcss.com (MIT)

== Source code ==

This plugin ships some minified JavaScript. The complete, un-minified source for every compiled file is included inside this plugin, and can be rebuilt with standard tools.

Gutenberg blocks — `build/blocks/{inline,modal,contact,content}/index.js`

* Source: the `blocks/` folder (React/JSX, built with @wordpress/scripts).
* Rebuild, from the plugin folder: `npm install` then `npm run build:blocks`.

Widget runtime (SDK) — `build/sdk/formvue-{inline,modal,contact,content}.js`

* Source: the `sdk-src/` folder (TypeScript + Preact + Tailwind CSS, built with Vite).
* Rebuild: `cd sdk-src` then `npm install` then
  `FORMVUE_API_URL=https://api.formvue.com FORMVUE_SHARE_URL=https://formvue.com npm run build:cdn`
  (without those variables the build targets localhost, which is the development default).
* The API type definitions in `sdk-src/src/shared/api/v1.d.ts` are generated from FormVue's public OpenAPI schema with the `openapi-typescript` tool; they are type-only declarations and contain no runtime code.

The bundled libraries listed under "Third-party libraries" (Preact, @preact/signals, @formisch/preact, valibot, openapi-fetch, Tailwind CSS) are all MIT-licensed.

== Installation ==

1. Upload the `formvue-lead-capture` folder to `/wp-content/plugins/`, or install it from the Plugins screen.
2. Activate the plugin through the Plugins menu.
3. Go to Settings → FormVue to configure defaults.
4. Add a widget using a shortcode, the Gutenberg block, or the Elementor widget.

== Frequently Asked Questions ==

= How do I get a Form ID? =

Log in to your FormVue dashboard at formvue.com, select a form, and copy the ID from the URL or share settings.

= Does it work with Elementor? =

Yes. Look for "FormVue" in the Elementor widget panel under the General category.

= Does it work with Divi? =

Yes. On Divi 5, native FormVue modules appear in the Visual Builder's module list with a live preview. On Divi 4, use a shortcode — `[fvlc_inline id="your-form-id"]`, `[fvlc_modal]`, `[fvlc_contact]`, or `[fvlc_content]` — in a Text or Code module.

= Does it work with WPBakery / other builders? =

Yes. Use a shortcode — `[fvlc_inline id="your-form-id"]`, `[fvlc_modal]`, `[fvlc_contact]`, or `[fvlc_content]` — in any text or HTML module.

= Can I have multiple widgets on one page? =

Yes. Each widget instance works independently.

= Does the plugin load any external scripts? =

No. The widget runtime is bundled inside the plugin and served from your own site. The plugin only contacts the FormVue API to record events and submit leads — see the "External services" section.

== Screenshots ==

1. The FormVue Gutenberg blocks with live preview.
2. The FormVue Elementor widgets and their controls.
3. The global defaults settings page (Settings → FormVue).

== Changelog ==

= 2.4.1 =
* Questions that every branch of a form leads to now show right away, before the question that branches is answered
* A failed submit no longer clears the form: after a network or server error the visitor is back on the form with every answer, the picked address and its USPS check intact, and can submit again

= 2.4.0 =
* Address fields suggest matching street addresses as the visitor types. Picking one also sends the street, city, state, and ZIP with the lead, so a submission that never opens the form link still carries a structured address
* A typed address that is not picked from the list settles on the suggestion it stands for, on Enter or on submit
* Address verification: when the form requires it, the address is checked with USPS on submit. A missing street number or apartment is asked for right below the address; an address USPS cannot confirm shows one warning and goes through on the next submit. A verification outage never holds a lead
* Forms follow their branching: a question shows only once the answer that leads to it is given, and questions on a branch the visitor did not take are neither required nor sent

= 2.3.3 =
* Fix Extra Params so they prefill the form when a visitor submits a phone number on desktop
* Stop sending Extra Params with impression and click events

= 2.3.2 =
* Add an Extra Params field to every widget, the Settings page, and the Elementor and Divi controls — give it a query string such as `service_type=permanent_architectural_lighting` and the form opens with those values prefilled

= 2.3.1 =
* Show quote-specific redirect messaging while the contact form opens the quote on mobile

= 2.3.0 =
* Native Divi 5 modules — all four widgets (inline button, modal, contact, content) appear in the Divi 5 Visual Builder with a live preview and full appearance/attribution settings

= 2.2.0 =
* Support `/blog/<slug>` URLs in auto campaign slug resolution — embeds on blog post pages now attribute to the post slug automatically
* Fix mobile redirect clickthrough for contact and content embeds

= 2.1.0 =
* Add a FormVue button directly to navigation menus (Appearance → Menus) — ideal for replacing a header "Request a Quote" link
* Hide the button label when it is set to an empty value (no leftover spacing)

= 2.0.0 =
* Renamed to "FormVue — Lead Capture" with the formvue-lead-capture text domain
* Bundled the SDK runtime inside the plugin (no external CDN script loading)
* Four independent widgets — inline, modal, contact, content — each as its own Gutenberg block, Elementor widget, and shortcode ([fvlc_inline], [fvlc_modal], [fvlc_contact], [fvlc_content]); every widget exposes only its relevant options
* Added campaign / UTM attribution and query-param passthrough
* Added locale, variant, and mobile new-tab options
* Documented external service usage; added GPLv2 license file

= 1.0.0 =
* Initial release
* Shortcode support
* Gutenberg block
* Elementor widget
* Global settings page

== Upgrade Notice ==

= 2.4.1 =
Fixes for branching forms and failed submits: shared questions show right away, and a failed submit keeps the visitor's answers.

= 2.4.0 =
Address fields suggest and verify street addresses, and forms follow their branching. Address verification uses a new external service (Lob, for USPS) — see "External services".

= 2.3.1 =
Clarifies the mobile contact-form handoff with quote-specific redirect messaging.

= 2.2.0 =
Adds automatic campaign attribution for blog post pages when using the auto campaign slug setting.

= 2.1.0 =
Adds a FormVue button as a navigation menu item and lets you hide the button label. Configure under Appearance → Menus.

= 2.0.0 =
Adds modal, contact, and content modes, bundles the widget runtime locally, and renames the plugin. Review Settings → FormVue after upgrading.
