=== Koala Forms ===
Contributors:      wpkoalaforms
Tags:              form builder, contact form, gutenberg, multi-step form, ai form generator
Requires at least: 7.0
Tested up to:      7.0
Stable tag:        1.3.1
Requires PHP:      7.4
License:           GPL-2.0-or-later
License URI:       https://www.gnu.org/licenses/gpl-2.0.html

Build contact forms, multi-step forms, and registration forms using Gutenberg blocks — now with an AI form generator to create forms from a plain-language description.

== Description ==

**Koala Forms** is a form builder plugin for WordPress that works within the Gutenberg block editor. Each form field is a block. Forms are embedded in pages and posts using a shortcode and submissions are stored in the WordPress database.

= Supported Fields =

* Text Field (with input masking)
* Email Field
* Textarea / Paragraph
* Number Field
* URL Field
* Dropdown (Select)
* Multi-Select
* Radio Buttons
* Checkboxes
* Date Field
* Address Field
* Disclosure / Consent
* Multi-Step Forms

= Features =

* **Gutenberg-blocks** — every field is a WordPress block, configured in the block editor
* **Multi-step forms** — built-in step navigation with configurable steps
* **Input masking** — format fields like phone numbers as users type
* **Form submissions** — stored in the WordPress database, viewable in the admin panel
* **CAPTCHA support** — integrates with Google reCAPTCHA
* **Email notifications** — send confirmation and notification emails on submission
* **AI Form Generator (Beta)** — describe the form you need in plain language and let AI generate the block structure for you. See the External Services section for details.

== Installation ==

1. Upload the plugin files to `/wp-content/plugins/koalaforms/`, or install via the WordPress plugin screen.
2. Activate the plugin through the **Plugins** screen in WordPress.
3. Go to **Koala Forms → All Forms** in the WordPress admin menu.
4. Click **Add New Form**, enter a name, and click **Create Form**.
5. The form opens in the Gutenberg block editor — use the block inserter to add fields.
6. Publish the form, then copy the shortcode (e.g. `[KoalaForms form_id="123"]`) and paste it into any page or post.

== Frequently Asked Questions ==

= Do I need to know how to code? =

No. Forms are built using the Gutenberg block editor — add fields, configure settings, and publish.

= Can I create multi-step forms? =

Yes. Multi-step forms with step navigation are supported. Use the Step block to divide your form into sections.

= Where are form submissions stored? =

Submissions are stored in your WordPress database and are accessible from **Koala Forms → Submissions** in the admin menu.

= How do I display a form on a page? =

After publishing a form, copy its shortcode from the Forms list (e.g. `[KoalaForms form_id="123"]`) and paste it into any page or post.

= Can I generate a form using AI? =

Yes. Go to **Koala Forms → AI Form Generator**, describe the form you need in plain language, and click **Generate**. The AI will produce the full block structure which you can then refine or edit. This feature is in Beta, requires the Anthropic AI provider to be configured in WordPress, and requires an internet connection.

= Is it compatible with my theme? =

Koala Forms works with standard WordPress themes. The form output uses minimal markup and can be styled with CSS.


== License ==

Koala Forms is licensed under the GNU General Public License v2.0 or later.
License URI: https://www.gnu.org/licenses/gpl-2.0.html

All bundled third-party libraries are GPL-compatible:

* Vue.js — MIT License — https://github.com/vuejs/core
* vue-the-mask — MIT License — https://github.com/vuejs-tips/vue-the-mask
* vue-recaptcha — MIT License — https://github.com/DanSnow/vue-recaptcha
* DOMPurify — MPL-2.0 / Apache-2.0 — https://github.com/cure53/DOMPurify
* uuid — MIT License — https://github.com/uuidjs/uuid
* Chart.js v4.5.1 — MIT License — https://www.chartjs.org
* @kurkle/color v0.3.4 — MIT License — https://github.com/kurkle/color#readme
* @vue/runtime-dom v3.5.13 — MIT License — https://github.com/vuejs/core
* @vue/shared v3.5.13 — MIT License — https://github.com/vuejs/core

== Development ==

This plugin uses a build process for its JavaScript assets. The minified files in the `build/` and `assets/` directories are compiled from source.

The full human-readable source code is available on GitHub:
https://github.com/wpkoalaforms/koalaforms

To build from source:

1. Clone the repository: `git clone https://github.com/wpkoalaforms/koalaforms.git`
2. Run `npm install`
3. Run `npm run build`
4. Run `npm run build-vue`

== External Services ==

= AI Form Generator — Beta =

This plugin includes an optional AI Form Generator powered by Anthropic's Claude. This feature is in **Beta** — our team is actively testing and refining it. It works exclusively with **Anthropic's Claude** models.

**What it does:** Converts a plain-language description entered by an admin into a Koala Forms block structure, so you can generate a working form without building it field by field. It uses Anthropic's **Claude Sonnet** model (with Claude Opus as a fallback).

**What data is sent and when:**
* When an admin uses the AI Form Generator and clicks **Generate**, the following is sent to Anthropic's Claude: the text prompt the admin entered, the current form's block structure (when refining an existing generated form), any file the admin chose to upload (PDF, image, or HTML), and the prompts from earlier in the same session used as conversation history.
* Only form creation information is ever shared. **No form submission data, visitor data, or any information collected through your forms is ever sent to Anthropic or any external service.**
* Data is only sent when an admin explicitly initiates a generation request. It is never sent automatically or on behalf of site visitors.


= Google reCAPTCHA =

This plugin optionally integrates with Google reCAPTCHA to help prevent spam form submissions. This feature is disabled by default and only active when a reCAPTCHA site key and secret key are configured in the plugin settings.

**What it does:** Verifies that a form submission was made by a human and not an automated bot.

**What data is sent and when:**
* When a visitor loads a page containing a Koala Forms form with reCAPTCHA enabled, Google's reCAPTCHA script is loaded from `https://www.google.com/recaptcha/api.js`. This may send the visitor's IP address and browser information to Google.
* When a visitor submits a form, the reCAPTCHA response token is sent from your WordPress server to `https://www.google.com/recaptcha/api/siteverify` to verify the submission. No personal form field data is included in this request.

**This data is sent to Google only when reCAPTCHA is enabled in the plugin settings.**

* Service provider: Google LLC
* Terms of Service: https://policies.google.com/terms
* Privacy Policy: https://policies.google.com/privacy


== Screenshots ==

1. The Koala Forms dashboard — manage all your forms in one place.
2. Building a form in the Gutenberg block editor — drag, drop, and publish.

== Changelog ==

= 1.3.1 =
* Minimum WordPress version updated. 

= 1.3.0 =
* AI Form Generator (Beta) — describe a form in plain language and let AI generate the full block structure. Feature is in Beta; our team is actively testing it.
* Report a Bug — admins can submit a bug report directly from the AI Generator page, sent to the Koala Forms support team
* Deactivation feedback — when deactivating the plugin, admins are optionally asked for a reason. Feedback is sent to the support team to help improve the plugin
* Form and submission deletion — permanently delete trashed forms and submissions; forms with existing submissions are protected from accidental deletion

= 1.2.0 =
* Standard templates — choose from pre-built form templates (registration, contact, and more) when creating a new form
* Embed & Preview panel — new block editor sidebar panel shows the form shortcode with a one-click copy button, and a "Create preview page" button that generates a draft WordPress page for testing
* Submission delete — individual submissions can now be deleted from the admin submissions page
* Block editor UI — redesigned General, Validation, and Form Settings panels with improved layout and usability
* Extension hooks — new filters (`koalaforms.formComponent`, `koalaforms_form_html_attributes`, `koalaforms_extra_block_types`) and field extension API for Pro and add-on module integration

= 1.1.0 =
* Analytics — submission chart added to the form analytics page
* Address field is now collapsible in the block editor
* Bug fix — multiple forms on the same page now load and submit independently
* Help text improvements and general UI cleanup across the admin
* Display Label added — lets you set a user-facing label separate from the unique field name
* Custom hooks added to support add-on integrations

= 1.0.0 =
* Initial release
* Gutenberg block-based form builder — text, email, number, URL, date, dropdown, multi-select, radio, checkbox, textarea, address, and disclosure fields
* Multi-step forms with step navigation
* Input masking for fields like phone numbers
* Form submissions stored in the database and viewable in the admin panel
* Google reCAPTCHA support
* Email notifications on submission
