=== 4WP FAQ ===
Contributors: 4wpdev, anatolikkk
Tags: faq, faq schema, accordion, json-ld, structured data
Requires at least: 6.6
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 2.6.5
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

FAQ schema for the core Accordion. Scan every question on your site into one registry, edit once, and build a searchable FAQ hub.

== Description ==

**Not another FAQ block.** 4WP FAQ wraps the core **Accordion** you already use, adds **FAQPage JSON-LD**, and turns every question on your site into one registry you can reuse, update everywhere, and show as a searchable hub. Your design stays the same.

https://www.youtube.com/watch?v=SI3slJFYVbg

👉 **Live demo, docs and comparison:** [4wp.dev/plugin/4wp-faq](https://4wp.dev/plugin/4wp-faq/)
💬 **Real hub with 296 questions in 9 categories:** [4wp.dev/faqs](https://4wp.dev/faqs/)

= Why 4WP FAQ =

* **Built on core.** A thin wrapper over the core Accordion. No new design, no lock-in: unwrap any time and the Accordion stays.
* **The only FAQ plugin that scans.** Questions live on your pages. A scan collects them into one registry. You never type a question twice.
* **Edit once, update everywhere.** Change a question in the registry and 4WP FAQ writes it onto every page listed in **Used in**.
* **SEO hub for free.** List, Categories, Search and Count blocks, pretty category URLs, category SEO titles, canonical and Open Graph. No Pro tier.
* **AI without a vendor.** Category copy through the standard **WordPress AI Client** (Connectors). No custom SDK, no API keys in the plugin.

= What you get =

* **FAQPage JSON-LD** — structured data for search engines and AI answers. Opt-in, site-wide or per block. Skips its own output when Yoast already prints FAQ schema.
* **Convert to FAQ** — one click on an Accordion, or **Transform to → 4WP FAQ** from Details, heading + paragraph pairs or a List.
* **FAQ registry** — every unique question with **Used in** sources, categories and a Dashboard. **Add FAQ** places a new question on every page of a category, or on one page.
* **FSE hub** — **4WP FAQ List**, **Categories**, **Count** and core **Search** with in-place filtering (Interactivity API). Nested categories, drag-and-drop order.
* **Polylang** — categories follow the page language; the Dashboard shows figures per language.
* **4WP Drive** — an H2 FAQ section with H3 questions in a Google Doc becomes a 4WP FAQ block on import.

A plugin by [4wp.dev](https://4wp.dev/). **4WP** is our project brand; this plugin is not affiliated with, endorsed, or sponsored by WordPress.

Source: [github.com/4wpdev/4wp-faq](https://github.com/4wpdev/4wp-faq) · More plugins: [4wp.dev/plugins](https://4wp.dev/plugins/)

= How to work with it (short path) =

1. In the editor, add a core **Accordion** (or select an existing one).
2. Click **Convert to FAQ** in the block toolbar (or insert the **4WP FAQ** block). You can also select existing **Details**, **Accordion**, or heading + paragraph blocks and use **Transform to → 4WP FAQ**.
3. Put the **question** in the Accordion Item heading and the **answer** in the panel.
4. Open **FAQ → Settings** and enable **FAQPage JSON-LD** if you want structured data on the front end.
5. Optional: complete registry setup → **Rescan** (Dashboard or Settings) → place **4WP FAQ List** and **4WP FAQ Categories** on a hub page or template.
6. Optional: **FAQ → Add FAQ** — question, answer, FAQ categories (every matching FAQ block) and/or one page. No place chosen: the row is registry-only until a scan drops it.
7. Optional: edit a registry FAQ and **Update** — the plugin writes that item onto every **Used In** page (question match uses the previous title if you renamed it).
8. Optional: configure **Settings → Connectors**, then **FAQ → Settings → AI** to allow field markup. On **FAQ → Categories**, edit a term and **Generate with AI**. Apply writes into the form; **Update** still saves.

The registry is a helper. Accordion items on pages are the source of truth. A scan rebuilds the CPT from the site. New answers reuse the markup wrapper of a sibling accordion item on that page.

= Blocks =

* **4WP FAQ** (`forwp/faq`) — wrap Accordion / Accordion Item for JSON-LD and registry scan
* **4WP FAQ List** (`forwp/faq-list`) — registry glossary: grouped or flat, include/exclude categories
* **4WP FAQ Categories** (`forwp/faq-categories`) — category nav that filters the List; nested terms collapse by default
* **4WP FAQ Count** (`forwp/faq-count`) — live count for All / category / search (`[forwp_faq_count]`)
* **4WP FAQ Card** (`forwp/faq-card`) — inner card for the List (not in the inserter)

= Key features =

* Wrap **Accordion** / **Accordion Item** (legacy **Details** still supported)
* **FAQPage JSON-LD** in the document head — site-wide toggle plus per-block override
* Optional **FAQ registry** — scan, **Used In**, edit-to-push, **Add FAQ** onto category pages or one page
* **FAQ categories** — manage in admin, assign per block, or create on scan from the page
* **Admin Dashboard** — status metrics, Rescan, hierarchical categories, reused / uncategorized
* **FSE hub blocks** — List, Categories, Count, Card
* Categories nav: nested terms collapse by default; visitors expand them and the browser remembers
* Preview count per category on the All view + optional pretty category URLs (`/hub-page/term-slug/`)
* Category SEO title / description / image fields; filled SEO title is used as-is (no site-name suffix); pretty URLs use a category canonical
* Drag-and-drop category order on **FAQ → FAQ Categories** — same order in admin lists, Dashboard, and front-end List / Categories blocks
* **Polylang** — categories follow the language of the page that owns the FAQ block
* Setup wizard for registry post type and taxonomy slugs
* **Convert to FAQ** toolbar and **Transform to → 4WP FAQ** (Accordion, Details, List, heading + paragraph — one or many); default Accordion template on insert
* **AI Assistant** — WordPress AI Client / Connectors; Generate with AI on FAQ category edit (description + titles + meta). Settings → AI is always visible; markup stays off until a connector is available and **Allow predefined field markup** is on

= AI Assistant =

Generation uses the **WordPress AI Client**. Configure a text-generation connector under **Settings → Connectors**. **FAQ → Settings** always shows an **AI** card; **Allow predefined field markup** stays disabled until a connector is available.

1. Complete registry setup so FAQ categories exist.
2. Open **Settings → Connectors** and finish a connector for text generation.
3. Under **FAQ → Settings → AI**, turn on **Allow predefined field markup**.
4. Edit a category on **FAQ → Categories**. **Generate with AI** fills **Description**, **Display title**, **SEO title**, and **SEO description** from the category name and questions in that term.
5. Review, **Apply** (or Apply all), then **Update**. Nothing is saved until you update the term.

The plugin does not ship API keys and does not call a model until a connector is configured. Which remote service receives the prompt depends on the connector the administrator selected.

= Development =

JavaScript and CSS are built with `@wordpress/scripts`. Human-readable source (`src/`, `webpack.config.js`, `package.json`) is in the public GitHub repository — not in the distributed ZIP.

From a clone:

1. `cd` into the plugin directory
2. `npm install`
3. `npm run build` — compiles block, admin, and setup apps into `build/`

== Installation ==

1. Upload to `/wp-content/plugins/4wp-faq/` or install from **Plugins → Add New**.
2. Activate **4WP FAQ**.
3. Add or convert Accordion blocks, then open **FAQ → Settings** for JSON-LD, registry, and optional AI options.
4. After registry setup + Rescan, add **4WP FAQ List** and **4WP FAQ Categories** on a page or template.
5. Optional: configure **Settings → Connectors**, then enable **Allow predefined field markup** under **FAQ → Settings → AI**.

== Frequently Asked Questions ==

= Does this replace the Accordion block? =

No. 4WP FAQ is a thin wrapper. Your theme and block styles stay the same. Accordion stays Accordion—4WP FAQ adds schema, optional registry, and hub tools around it.

= How do I add a new FAQ question? =

1. Edit a page or post.
2. Insert **Accordion** (or **4WP FAQ**, which starts with an Accordion).
3. Click **Convert to FAQ** if you started from a plain Accordion.
4. Or select one or more **Details** / **Accordion Item** blocks (or heading + paragraph pairs) and use **Transform to → 4WP FAQ**.
5. One Accordion Item = one question (heading) and one answer (panel).
6. If you use the registry: open **FAQ → Dashboard** or **Settings** and run **Rescan registry** so the question appears under All FAQs.

There is no manual “Add New” registry editor. **FAQ → Add FAQ** is a short how-to only.

= Is JSON-LD / FAQ schema enabled by default? =

No. Structured data is opt-in so you control when Google sees FAQ markup.

* Site-wide: **FAQ → Settings → FAQPage JSON-LD**
* Per block: block sidebar → JSON-LD on front end (On / Off / inherit)

Schema is printed in the document **head** on singular pages that contain FAQ blocks. The registry is **not** required for JSON-LD.

= How do I check that FAQ schema is working? =

1. Enable JSON-LD in Settings (or for the specific block).
2. View the published page.
3. Use [Google Rich Results Test](https://search.google.com/test/rich-results) or view page source and search for `FAQPage`.

If Yoast SEO is active and outputs FAQ schema for the same content, 4WP FAQ skips its own output to avoid duplicate FAQPage graphs.

= What is the FAQ registry? =

An optional post type that **aggregates** unique questions found in your content after a scan. Use it to:

* Browse all questions in one place
* See where a question is reused (“Used in”)
* Build a public FAQ hub with List + Categories blocks

In-place FAQ blocks on product or landing pages keep working either way.

= How do I build an FAQ hub page? =

1. Complete registry setup and run **Rescan**.
2. Create a page (for example `/faq/`).
3. Add **4WP FAQ Categories** (nav) and **4WP FAQ List** (questions).
4. Optionally add core **Search** and enable **Filter 4WP FAQ List** in that block’s sidebar.
5. Optionally add **4WP FAQ Count**.

List and Categories share include/exclude filters so the nav and list stay aligned.

= What are pretty category URLs? =

When **Pretty category URLs** is on in Settings **and** on the Categories block:

* Category links become `/your-hub-page/term-slug/`
* **On-page title:** category **Display title** (empty: category name) in core **Title** (`core/post-title`), **Query Title** (`core/query-title`), or **Term Name** (`core/term-name`). The template chooses h1–h6. Heading blocks are not swapped.
* **On-page description:** category **Description** in core **Excerpt** (`core/post-excerpt`) or **Term Description** (`core/term-description`)
* Optional category **SEO title** / **SEO description** drive the document title and meta
* **Canonical** / `og:url` is the category URL (`/hub/term-slug/`), not the hub
* **SEO image** on the category is used for Open Graph / Twitter; empty uses the hub page image
* The List does not repeat the category name as an H2 when the page title already shows it
* JSON-LD on that URL is limited to that category

When off, category clicks filter the list **in place** and the page URL does not change.

= How do category SEO titles work? =

On each FAQ category term you can set **SEO title** and **SEO description**.

* If **SEO title** is filled → the browser / document title uses that string **exactly** (no “ – site name” appended).
* If it is empty → Display title + site name (WordPress default pattern).

See **FAQ → Settings → Documentation** for on-page title / description and document title / meta rules.

= When should I Rescan? =

After you add, edit, or remove FAQ blocks on published content. Rescan is available on:

* **FAQ → Dashboard** (Status widget)
* **FAQ → Settings** (Rescan registry)

Scans also schedule automatically when relevant posts are saved.

= Why does wordpress.org show only one block? =

Older packages registered List / Categories / Count from PHP only. From 2.2.0 each public block declares `editorScript` (and styles where applicable) in its `block.json` so the directory can discover them. Update to the latest ZIP if the listing looks incomplete.

= How do I filter the FAQ list with Search? =

Add a core **Search** block on the same page as **4WP FAQ List**. In the block sidebar: **4WP FAQ → Filter 4WP FAQ List**. Typing filters cards in place and does not run a site search.

= Does the plugin duplicate my FAQ text? =

No for the front end of in-place blocks—the Accordion content you write is the source of truth. The registry stores aggregated copies for listing and stats; answers still come from scanned content, not a second public editor workflow.

= What happens if I reset setup? =

You can choose new registry slugs in the wizard again, but FAQ **categories are removed**. Existing registry posts remain on the previous post type until you complete setup and run a new scan.

= Does it work with Polylang? =

Yes for registry categories during scan: terms follow the language of the page that contains the FAQ block. WPML is not integrated yet.

= Can editors use the Dashboard? =

Yes. **FAQ → Dashboard** is available to users who can edit posts. **Rescan** and **Settings** require manage options (administrators).

= How does the AI Assistant work? =

It uses the standard **WordPress AI Client**, not a separate 4WP AI plugin. Configure a text-generation connector under **Settings → Connectors**. The **AI** card is always visible under **FAQ → Settings**; you cannot enable **Allow predefined field markup** until a connector is ready. On a FAQ category edit screen, **Generate with AI** proposes Description, Display title, SEO title, and SEO description. Apply writes into the form; **Update** saves. Without a connector, Generate stays unavailable on category screens.

== Screenshots ==

1. A live FAQ hub on 4wp.dev: 296 questions, category navigation, search and count — built from the 4WP FAQ registry.
2. Convert to FAQ: one click wraps a core Accordion. Your design stays the same.
3. One Accordion Item = one question (heading) and one answer (panel).
4. FAQ → Settings: turn on FAQPage JSON-LD site-wide or per block.
5. FAQ Dashboard: registry status, Rescan, questions by category, reused and uncategorized.
6. Build the hub in the Site Editor: Categories, List, Search and Count blocks.
7. Add FAQ: place a new question on every page of a category, or on one page.
8. Edit once in the registry — the update is written to every page in Used in.
9. Generate category description and SEO titles with the WordPress AI Client.

== External services ==

This plugin optionally sends prompts through the **WordPress AI Client** when an administrator configures a connector under **Settings → Connectors** and runs **Generate with AI** on a FAQ category.

**WordPress AI Client / Connectors** (optional)

The plugin sends a prompt (site name, category name, question titles in that category, and current field values) through `wp_ai_client_prompt()`. The WordPress AI Client routes that prompt to the connector the administrator selected. This plugin does not call model vendors directly; which remote service receives the prompt depends on that connector. No visitor or front-end user data is sent. Nothing is generated until a connector is configured and **Allow predefined field markup** is on.

== Changelog ==

= 2.6.5 =
* **Directory assets:** animated banner and icon GIFs for WordPress.org; nine screenshots aligned with the current hub and editor UI.
* **Docs:** README and readme.txt refreshed for the directory listing (demo, comparison, video).

= 2.6.4 =
* **Hub filter:** the host page slug (e.g. `/4wp-faq/`) no longer activates a FAQ category with the same slug. Pretty category URLs still match the full nav path (`/4wp-faq/hooks/`). Accordion FAQ on the page is unchanged; List / Categories keep their own settings.
* **Editor:** Include/Exclude category tokens no longer freeze the editor (Maximum update depth) when List and Categories sync filters.
* **Convert to FAQ:** wrapping an Accordion no longer drops its items (toolbar used empty innerBlocks). **Unwrap 4WP FAQ** restores the Accordion / Details.

= 2.6.3 =
* **Typography:** List, Card, and Categories panels match core (size, appearance, line height, letter spacing, decoration, letter case).
* **Used in:** sources stay on one line with a separator. Non-public sources are hidden on the front; the editor preview shows them greyed.
* **Count:** the badge is the sum of the categories on All, or that category’s count on a category page. The number and the label stay on one line.
* **No results:** an empty search shows a message you can edit, the same way as Query Loop no-results.
* **Dashboard:** figures follow the Polylang admin language and name it. All languages adds a per-language breakdown. Reused counts public pages only.
* **Editor preview:** List and Categories follow the page language, and Exclude hides that category.

= 2.6.2 =
* **Editor:** List, Categories, and Count previews load with POST, so the editor no longer shows “Error loading block: [object Object]”.
* **Answers:** color classes copied from dark sections (such as `has-white-50-color`) are stripped on output, so answer text uses the card color.
* **Settings:** Overview is four blocks — Registry, SEO, AI, Category titles. A click opens that section. Card headers are shorter, and the Connectors notice sits apart from the toggle.
* **Dashboard:** FAQ Status uses large figures. In two columns the third column stacks on the right instead of covering the first. The main WordPress Dashboard has a short FAQ widget with a link to this dashboard.

= 2.6.1 =
* **4WP Drive** — register the FAQ wrap for import mapping: H2 FAQ section + H3 Q&A become a `forwp/faq` accordion. Drive Patterns → Integrations Plugins lists this plugin when it is active. See [4WP Drive](https://wordpress.org/plugins/4wp-drive/).

= 2.6.0 =
* **Registry edit:** Update a FAQ record (title + answer) to write that item onto every **Used In** page. Renamed questions are found via the previous title.
* **Add FAQ:** create a registry post; FAQ categories append the item to every matching `forwp/faq` block; **One page** limits that to a single post/page that already has a FAQ block. Neither: registry-only until a scan drops it.
* New answers copy the sibling accordion-item wrapper (heading + panel markup) and fill in your text; the wrapped HTML is saved back on the registry record.
* Site content stays the source of truth. Rescan / reinstall rebuilds the registry from pages.

= 2.5.0 =
* **AI Assistant:** generate FAQ category Description, Display title, SEO title, and SEO description via the standard WordPress AI Client (Settings → Connectors).
* Settings → AI card is always visible; **Allow predefined field markup** stays disabled until Connectors support text generation.
* Docs: WordPress.org readme documents Connectors, FAQ, and External services.

= 2.4.0 =
* **FAQ Categories:** collapse nested terms by default (block inspector toggle). Visitors can expand/collapse parents; the choice is remembered in the browser. The branch for the current category stays open.
* Pretty category URLs swap **Display title** into core Title / Query Title / Term Name, and **Description** into core Excerpt / Term Description. Heading level stays with the template.
* Pretty category URLs: `<link rel="canonical">` and `og:url` point at `/hub/term-slug/` (not the hub). **SEO image** on the category is used for Open Graph / Twitter; empty falls back to the hub page image. List group H2 is omitted when the page title already shows that category.

= 2.3.0 =
* Requires WordPress **6.6+** (Interactivity API for List / Categories hub).
* Convert selected **Details**, **Accordion** / **Accordion Item**, heading+paragraph pairs, or a **List** to **4WP FAQ** via Transform to and the Convert to FAQ toolbar (one or many items).
* Category SEO title: when filled, the document title is used as-is (no site-name suffix).
* Admin **Dashboard** under the FAQ menu: status metrics, Rescan, hierarchical By category (collapsible, inclusive counts), reused / uncategorized.
* **FAQ Categories**: drag-and-drop term order applies in admin lists and on the front end (ensures `term_order` column when missing).
* Settings: compact layout plus how H1 / document title / meta description are built for category URLs.
* Docs: hub blocks for page building and core Search → Filter 4WP FAQ List.
* Add FAQ in admin is a short how-to (registry posts are created by scan, not by hand).
* List/Card: Question / Answer typography on the Styles tab.

= 2.2.0 =
* Listing: declare `editorScript` / `style` in block.json for List, Categories, Count, and Card so wordpress.org discovers hub blocks (not only the FAQ wrapper).
* Contributors: add `anatolikkk` (Anatoliy Dovgun) alongside `4wpdev`.
* Add **4WP FAQ Count** block and `[forwp_faq_count]` shortcode.
* Hub: per-category preview on All view, “View all” links, SEO/pretty category URLs, category SEO title/description, drag-and-drop term order.
* Card: optional “Used in” source links from registry usage meta.
* Admin: preview-per-category and SEO URL settings; clearer JSON-LD help for hub pages.

= 2.1.0 =
* Add FSE registry hub blocks: **4WP FAQ List**, **4WP FAQ Card**, **4WP FAQ Categories**.
* Shared include/exclude filters between List and Categories (Interactivity API).
* Registry content helpers and front-end FAQ view script.

= 2.0.3 =
* Fix: FAQPage JSON-LD uses `<summary>` text as `Question.name` for core Details blocks (no longer duplicates the answer).
* Fix: FAQPage JSON-LD outputs in `<head>` for reliable detection by validators and crawlers.
* Add: `@id` and `url` on FAQPage schema.

= 2.0.2 =
* Maintenance release.

= 2.0.1 =
* Fix: incomplete plugin uploads no longer white-screen the site — missing PHP files show an admin error and the plugin stops loading safely.
* Deploy: ensure `includes/class-category-resolver.php` and other required files are present when updating from 2.0.0.

= 2.0.0 =
* Registry categories: none, existing, or create new per FAQ block (applied on scan).
* Categories can be managed in admin or derived from the pages where FAQ blocks are placed.
* Polylang: language-aware FAQ categories during registry scan.
* Block editor: default Accordion with one item on insert; **Add FAQ item** button.
* WPML support planned for a future release.

= 1.0.0 =
* Initial release: `forwp/faq` wrapper, setup wizard, registry scan, JSON-LD, admin settings UI.

== Upgrade Notice ==

= 2.6.5 =
WordPress.org banner/icon GIFs and screenshots; directory docs refresh. No functional change from 2.6.4.

= 2.6.4 =
Hub List no longer disappears when the page slug matches a FAQ category. Convert to FAQ keeps Accordion items; Unwrap restores them. Include/Exclude no longer freezes the editor.

= 2.6.3 =
Typography matches core, Used in stays on one line, the count matches the categories on the page, empty search has an editable message, and the dashboard follows the admin language.

= 2.6.2 =
Editor previews load again, FAQ answers no longer keep a forced light color, Settings opens from Overview blocks, and the FAQ Dashboard shows large figures plus a widget on the main WordPress Dashboard.

= 2.6.1 =
Registers the FAQ block with 4WP Drive so imported documents can map an FAQ heading to forwp/faq. https://wordpress.org/plugins/4wp-drive/

= 2.6.0 =
Edit or Add FAQ in the registry: Update pushes onto Used In pages; Add FAQ with categories or one page inserts a new accordion item. Unplaced rows are dropped on scan. Site pages stay the source of truth.

= 2.5.0 =
Optional AI category copy via WordPress Connectors. FAQ → Settings → AI is always visible; enable markup after Connectors are ready, then Generate with AI on a category.

= 2.4.0 =
Category nav collapses nested terms by default. Pretty category URLs fill core Title / Query Title / Term Name and Excerpt / Term Description, use a category canonical and SEO image (hub image if empty), and skip the duplicate list H2 when the page title already shows the category.

= 2.3.0 =
Requires WordPress 6.6+. Dashboard, drag-and-drop category order, category title rules, Transform to 4WP FAQ for selected Details/Accordion items, and filled SEO titles no longer append the site name.

= 2.2.0 =
Hub blocks visible on the plugin directory, Count block, preview/SEO URL settings, and Anatoliy Dovgun as contributor. Re-upload screenshots to SVN assets if captions still show empty images.

= 2.1.0 =
Adds registry FAQ List, Card, and Categories blocks for FSE hubs.

= 2.0.3 =
Fixes FAQPage schema for Details blocks and moves JSON-LD to the document head.

= 2.0.1 =
Hotfix for incomplete updates: safe load when plugin files are missing. Re-upload the full 2.0.1 package if you saw a fatal error on 2.0.0.

= 2.0.0 =
Registry categories, Polylang-aware scan, and improved FAQ block insertion (default Accordion + Add FAQ item).

= 1.0.0 =
Initial release.