=== HS Product Filters for WooCommerce ===
Contributors: hookspark
Requires at least: 6.8
Tested up to: 7.1
Requires PHP: 8.2
Requires Plugins: woocommerce
Stable tag: 1.2.3-dev
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

AJAX catalog filters with consistent variation matching and selective SEO landing pages.

== Description ==
Create named filter configurations in HookSpark > Product Filters. Preview categories, tags, native brands and global attributes against the actual WooCommerce catalog, with price and stock constraints.

Embed an enabled set using [hs_product_filters set="SET_ID"]. One set per dedicated page is supported in this version. GET forms work without JavaScript; AJAX replaces only the catalog fragment and updates browser history. No archive replacement yet. Named SEO landings use native WordPress pages. Full-page HTML is fetched from the same URL; no separate public write endpoint is exposed. Pretty permalinks are the tested route.

OR within a dimension; AND across dimensions; all constraints must match the same variation. Counts are distinct parent products with the counted dimension's selection omitted. Prices follow WooCommerce display taxation. FOX Currency Switcher 1.5.4 passed scoped USD/EUR fixed-rate filtering checks on WordPress 6.8/WooCommerce 10.6.0 using its default transient storage. Its selector reload clears AJAX selections. Cookie storage, GeoIP, fixed product prices, cached shops, checkout conversion and other providers remain unverified.

The catalog reader uses bounded batches and supports currencies with zero to six decimal places. Standard catalogs use a direct reader; customized pricing, queries, eligibility or product stores automatically retain native WooCommerce reads. There is no 500-product or 5,000-row truncation. Each filter request still evaluates the eligible catalog. Local mixed-catalog measurements were about 0.73 seconds at 10,000 parents and 4.12 seconds at 50,000 parents; these exclude HTTP/rendering overhead and are not hosting response-time guarantees. Test your own catalog and customizations before deployment. Request-local cache memory is released only when the cache provider explicitly supports that operation; persistent cache is never flushed. Preview shows six cards and up to 30 values per dimension. Simple and variable products only. Configuration allows up to eight taxonomy filters and 100 sets.

== SEO landing pages ==
In Product Filters > SEO landing pages, connect an existing WordPress page containing exactly one [hs_product_filters] shortcode to an enabled set and one taxonomy term. Write its SEO title and description. Use the native page editor for its readable URL, heading, content and publication status. The SEO editor never publishes or rewrites page content. Enable indexing only for useful, distinct editorial pages; default is noindex. Up to 100 page bindings are supported.

Additional filters, price/stock constraints, nondefault sorting and pagination remain noindex and do not inherit the editorial metadata. Exact equivalent selections use the native page canonical when indexing is permitted. Empty/invalid filtered HTML returns 404 while preserving usable controls; AJAX can render that recovery state. Temporary catalog failures return 503. Global noindex and existing SEO-provider restrictions are never removed. robots.txt is not modified: blocking crawling can prevent crawlers from reading noindex.

Native sitemap excludes noindex, unavailable and empty configured landings. Installed Yoast SEO 28.5 and Rank Math 1.0.278 passed the metadata, robots, canonical and sitemap acceptance matrix on WordPress 7.1.1, WooCommerce 11.1.0 and PHP 8.2.29. Other versions remain unverified. Provider sitemap caches are refreshed after filter settings, catalog or site-visibility changes. Other SEO plugins or themes producing their own descriptions require verification. Arbitrary filter URLs are not automatically converted to pretty URLs: readable URLs belong to deliberately created WordPress pages. Generated filter parameters are normalized. Mass landing generation and automatic metadata for combinations are not provided.

== Data policy ==
Settings are site-scoped and retained on deactivation or removal. This build writes no product, stock, cart or order data. No external services or telemetry. No stable public developer API is provided yet.

Catalog pages send no-store/private cache directives and set the conventional DONOTCACHEPAGE flag before rendering. Exclude their URLs from full-page caches/CDNs and purge older cached copies when enabling or updating the plugin. An upstream cache that serves a page before WordPress runs or ignores origin directives requires explicit exclusions; WP Super Cache 3.1.3 Simple mode passed scoped anonymous-page bypass tests on WordPress 6.8/WooCommerce 10.6.0. Expert mode, CDN behavior and other providers are unverified; no universal cache-provider compatibility is claimed.

== Editions ==
Free includes catalog filtering and automatic noindex. Pro adds dedicated filter-page creation and editing, readable URLs, selective indexing, titles, descriptions, canonical handling and portable filter-set import/export. Existing saved SEO pages continue working unchanged without Pro; creating or editing their settings requires Pro. No license is required for Free. The new editions are development candidates pending release acceptance.

== Changelog ==

= 1.2.3-dev =
* 2026-10-10: Updated the packaged compatibility documentation after the 9–10 October checks. Selected paths checked with Elementor Free 4.3.4 and Pro 4.3.1, WordPress 7.1.3, WooCommerce 11.1.0 and PHP 8.2.29. The plugin’s own [hs_product_filters] catalog worked inside Elementor Shortcode, with selected filtering and responsive display. Both editions passed native coexistence checks with Free and Pro active. This does not connect filters automatically to Elementor Pro Products, Archive Products or Loop Grid queries. Use the plugin catalog for this tested path. Details: https://hookspark.dev/product-filters/#compatibility


= 1.2.2-dev =
* Add optional WordPress Abilities/MCP access: read supported configuration and prepare validated proposals for same-user browser approval.
* Reuse one HookSpark AI access switch and review screen across installed plugins.
* Configuration changes are saved only after human approval; proposals expire after 15 minutes.

= 1.2.1-dev =
* 2026-10-06: Documented selected Astra and WPML/WCML compatibility checks. See the compatibility notes at https://hookspark.dev/product-filters/#compatibility. Scope is limited to the recorded versions and scenarios; no universal compatibility certification. This package update documents testing and preserves the functional fixes listed in earlier entries.


= 1.2.0-dev =
* Separate dedicated SEO page editing into Pro; retain saved pages and automatic noindex in Free.
* Show locked SEO controls in Free and reject unauthorized edition writes on the server.


= 1.1.0-dev =
* Add the shared Import / export workspace and clear Pro controls. Existing filters, SEO pages and settings are preserved.

= 1.0.1 =
* Use shared HookSpark edit, duplicate and trash icons in the filter-set list.
* Refine rounded inputs and selects, label spacing and action spacing in admin and storefront filters.

= 1.0.0 =
* Initial stable package prepared for release: shortcode catalogs, same-variation matching and AJAX navigation.
* Configure readable single-filter landing pages with editorial metadata and selective noindex.
* Use the shared HookSpark admin workspace, EN/IT messages and keyboard-friendly controls.
* Retain catalog/settings on removal and use native WooCommerce reads when customizations require them.


= 0.8.3-dev =
* Use native singular/plural result messages in English and Italian across frontend and admin previews.
* Prevent shared page-cache storage on shortcode catalog pages, including the unfiltered initial view.
* Strengthen price-field, select and drawer cancel boundaries independently of decorative card borders.
* Keep search beside its field, remove competing create actions in editors, and show embed codes only for saved sets.
* Report parent catalog query failures as unavailable instead of returning empty or incomplete results.
* Read standard catalogs in bounded batches; automatically retain native WooCommerce objects for custom pricing, eligibility, queries and product stores.
* Preserve native scheduled-sale prices, imported tax defaults and variation ordering in the fast reader.
* Version frontend and private admin assets from the installed plugin header to refresh caches after updates.
* Preserve keyboard focus during automatic filter updates; explicit Apply, reset and pagination still move to results.
* Batch native parent, variation and metadata cache reads while retaining WooCommerce eligibility, price hooks and child selection.
* Stop sitemap catalog scans once every eligible single-term landing has a matching public product. Empty landings still exhaust the catalog.


= 0.8.2-dev =
* Adopt the shared HookSpark admin header, tabs, buttons and plugin catalog.
* Add Start here guidance and keep SEO navigation consistent.


= 0.8.1-dev =
* Explain invalid prices beside the affected field, preserve input and focus correction in desktop, mobile and admin previews.
* Reject conflicting page slugs or published landing URLs that do not resolve to their selected page before saving SEO settings.
* Review native pages and SEO bindings using a set before moving it to Trash.
* Explain admin preview matching and show attributes of the matching variation alongside its ID.
* Inherit theme typography and WordPress base/contrast colors, with scoped merchant color overrides.
* Reconcile a page restored from browser memory with its active filter URL without adding history entries.
* Associate configuration and SEO errors with their fields, link the summary to invalid controls and retain valid draft values.

= 0.8.0-dev =
* Keep mobile retry controls in view and distinguish explicit admin form submissions from leaving unsaved changes.
* Preview draft SEO landing URL, metadata, matching count and indexing constraints before saving or publishing anything. Explain landing permission, site visibility, planned canonical and external checks separately.
* Choose whether category boundaries and category filters include descendants, preserving existing defaults.
* Normalize generated filter URLs and retry the exact failed catalog update while ignoring stale network errors.

= 0.7.1-dev =
* Prime missing WordPress and WooCommerce metadata caches from one bounded native read, preserving warm caches and native metadata hooks.

= 0.7.0-dev =
* Keep the last ten changed configurations per filter set and load previous versions as inactive drafts, with validation and conflict protection.

= 0.6.2-dev =
* Reuse one native facet-count scan per filter set while generating page sitemaps. Retain only configured landing terms in request memory.
* Invalidate request counts after catalog/configuration changes and leave product sitemap entries untouched.

= 0.6.1-dev =
* Refresh provider page sitemaps after filter configuration and catalog changes; exclude configured landings when the site discourages indexing.
* Keep native descriptions available while an installed SEO provider has not initialized its head output.
* Verify Yoast 28.5 and Rank Math 1.0.278 using actual HTTP pages and XML sitemaps.

= 0.6.0-dev =
* Mobile filter drawer with native modal focus handling, draft selections, explicit apply and cancel/Escape restoration.
* Without JavaScript, the existing page-navigation filter controls remain available.

= 0.5.3-dev =
* Batch missing native WooCommerce metadata reads and prime variation batches, preserving native metadata filters, IDs and CRUD invalidation. Custom product data stores retain their own reads.
* Reduces database query count; complete-catalog scanning remains and large-catalog response time is not certified.
* Respect page-authoring capabilities when showing SEO setup actions; existing page bindings remain editable when authorized.

= 0.5.1-dev =
* Show removable active taxonomy values, price limits and availability above the catalog.
* Removal preserves other selections and sorting, returns to page one, and works with or without JavaScript.
* Removing a landing default broadens browsing without inheriting index permission.

= 0.5.0-dev =
* Add editorial single-filter landing bindings with opt-in indexing, native readable page URLs and custom title/description.
* Apply scoped noindex to combinations; preserve global restrictions and exclude unavailable landings from the native sitemap.
* Return 404 for empty/invalid filtered HTML, update metadata with AJAX/history, and preserve plain-permalink GET routing.
* Add preliminary Yoast and Rank Math metadata/sitemap adapters; integration certification remains open.

= 0.4.0-dev =
* Stream native catalog candidates and retain only the requested result window.
* Preserve same-variation matching and distinct-parent facet counts across batches.
* Remove fixed catalog caps; benchmark confirms large-catalog latency still needs optimization.

= 0.3.0-dev =
* Search saved sets, duplicate as inactive, move to Trash with exact-name confirmation, restore as inactive.
* Preserve saved sets across concurrent actions; reject malformed registry documents.
* Price filtering supports zero to six decimal places; admin preview now uses matched variation images.

= 0.2.0-dev =
* Public shortcode, progressive GET/AJAX filtering, history, sorting and pagination.
* Matched variation images and links. Responsive scoped frontend controls.
* Company demo with five original images (not included in the customer plugin).

= 0.1.0-dev =
* First internal configuration editor with privately bundled HookSpark Core.
* Canonical state and variation-aware matching, contextual distinct-parent counts.
* Native read-only catalog preview and atomic versioned settings.
* Italian interface, responsive admin and unsaved-change guard.
