=== FilterOrbit: Advanced Product Filters for WooCommerce ===
Contributors: sakibbd08
Tags: product filter, ajax filter, woocommerce filter, ajax product filter, layered navigation
Requires at least: 6.0
Tested up to: 7.1.2
Requires PHP: 7.4
Requires Plugins: woocommerce
Stable tag: 1.0.3
License: GPL-2.0-or-later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Advanced zero-request product filters for WooCommerce with AI search, visual discovery, and a React filter designer.

== Description ==

FilterOrbit adds a powerful, instant-filtering sidebar to your WooCommerce store. All filtering runs client-side on a pre-cached product array — no page reloads, no AJAX round-trips.

**Features**

* Zero-request filtering — filters run entirely in the browser on a cached product array.
* AI natural language search — type plain-English queries to filter products.
* Visual discovery — image swatch grid for colour and style filtering.
* Predictive personalisation — quick picks based on browsing session.
* Range histogram — price slider with distribution bars.
* Drag-and-drop filter designer — build your sidebar layout in the admin.
* Per-filter colour settings — customise pill colours, slider colours, and card tints independently.
* WooCommerce attribute support — automatically discovers global and custom product variation attributes.
* Multi-category / multi-tag — products with multiple categories and tags match all their values.

== Installation ==

1. Upload the `filterorbit-product-filters` folder to the `/wp-content/plugins/` directory.
2. Activate the plugin through the **Plugins** screen in WordPress.
3. Go to **FilterOrbit** in the admin menu and design your filter layout.
4. Add the shortcode `[filter_orbit]` to any page, or enable the automatic shop sidebar in settings.

== Frequently Asked Questions ==

= Does it require WooCommerce? =

Yes. FilterOrbit requires WooCommerce to be active.

= Does filtering require AJAX calls? =

No. All product data is pre-loaded on page render and filtering runs entirely in the browser with zero network requests. You get the instant, no-reload experience of an AJAX product filter without the server round-trips. The only request FilterOrbit makes is the optional AI natural-language search, and only when you have configured an AI provider.

= How do I add the filters to my shop? =

Add the shortcode `[filter_orbit]` to any page, post, or block (use the Shortcode block in the block editor). The layout you save in **FilterOrbit > Filter Designer** is what visitors see.

= Which filters are available? =

Product category, product tag, price (range slider with histogram), and every global or custom WooCommerce attribute, including variation attributes such as colour and size. Each filter can be shown as a checkbox list, pills, a range slider, or a visual discovery swatch grid.

= How do I set up AI natural-language search? =

Go to **FilterOrbit > AI Settings**, choose OpenAI or Google Gemini, paste your API key, pick a model, and enable the AI Natural Language Filter in **FilterOrbit > Settings**. Shoppers can then type queries like "blue shirts under $30" and the matching filters are applied automatically. If the AI provider is unreachable, FilterOrbit falls back to a built-in keyword parser.

= Is the AI search free? =

The feature is included in the plugin at no cost. You pay your AI provider directly for API usage; Google Gemini offers a free tier that is enough for most small stores.

= Will it work with my theme? =

FilterOrbit renders inside its own scoped container with prefixed CSS classes, so it does not conflict with theme styles. It works with both block themes and classic themes.

= How many products can it handle? =

FilterOrbit pre-loads up to 100 published products on the page so filtering is instant. It is designed for small and medium catalogs where instant, no-reload layered navigation matters most.

= Can I change the text shown to shoppers? =

Yes. **FilterOrbit > Language** lets you edit every front-end label, placeholder, and message. The plugin is also translation-ready using the `filterorbit-product-filters` text domain.

= Can I customise the colours? =

Yes. Each filter block has independent colour settings in the Block Settings panel of the filter designer. Slider filters, pill/category filters, and layout blocks each expose the colour controls that are relevant to them.

== Screenshots ==

1. Storefront: filter sidebar with category checkboxes and price histogram, AI search bar, and product cards with add-to-cart buttons.
2. AI natural-language search: "shirts under 20" ticks the Shirts category and sets the price range automatically.
3. Filter Designer: drag and drop filters into columns and set column widths.
4. Settings: enable AI search, visual discovery, personalisation, product counts, and client-side caching.
5. Product quick view: image slider, price, stock status, scrollable description, quantity, and add to cart without leaving the page.

== External services ==

FilterOrbit includes an optional AI natural-language search feature. When enabled and configured, the plugin sends product search queries and product data to third-party AI services. This feature is **opt-in** — it only activates if you enter an API key in the AI Settings screen. No data is sent without your explicit configuration.

**OpenAI**

* What it is: A third-party AI platform (https://openai.com).
* What it is used for: Processing natural-language search queries and optionally generating product embeddings for semantic search (RAG).
* What data is sent: The user's search query text, and (when indexing is enabled) product titles, descriptions, categories, tags, and attributes.
* When data is sent: Only when a visitor submits a natural-language search and AI is enabled and configured with a valid API key.
* Terms of service: https://openai.com/policies/terms-of-use
* Privacy policy: https://openai.com/policies/privacy-policy

**Google Gemini**

* What it is: A third-party AI platform provided by Google (https://ai.google.dev).
* What it is used for: An alternative AI provider for natural-language query processing and product embeddings.
* What data is sent: The user's search query text, and (when indexing is enabled) product titles, descriptions, categories, tags, and attributes.
* When data is sent: Only when a visitor submits a natural-language search and AI is enabled and configured with a valid Gemini API key.
* Terms of service: https://ai.google.dev/gemini-api/terms
* Privacy policy: https://policies.google.com/privacy

If you do not enter any API keys in the AI Settings screen, no data is ever transmitted to these services.

== Source code ==

The compiled JavaScript assets (`assets/admin/filter-orbit-admin.js` and `assets/frontend/filter-orbit.js`) are built from human-readable React/TypeScript source files. The full source code is publicly available at:

https://github.com/sakib08/FilterOrbit

Build instructions (requires Node.js 18+):

1. `npm install`
2. `npm run build`

== Changelog ==

= 1.0.3 =
* New: Product quick view modal with image slider, price, stock status, scrollable description, variation selection, quantity, and add to cart.
* New: Add to cart / Select options button on every product card.
* New: Product card and quick view labels are editable in FilterOrbit > Language.
* New: AI Settings are now free for everyone.
* Fix: AI natural-language search now works with Google Gemini (requests run server-side through a new REST endpoint).
* Fix: Retired Gemini models no longer break AI search; the plugin automatically falls back to a working model.
* Fix: AI search results no longer disappear because the whole sentence was also used as a keyword search.
* Fix: Pressing Enter in the AI search box submits the search on all themes.
* Tweak: Cleaner AI search bar without the section heading, title, and icon badge; the send button no longer has a background.
* Tweak: Updated Gemini model list (gemini-3.8-flash is the new default).
* Tweak: Tested up to WordPress 7.1.2.

= 1.0.2 =
* UI update

= 1.0.1 =
* Initial release.

== Upgrade Notice ==

= 1.0.3 =
Adds a product quick view with add to cart and fixes AI natural-language search with Google Gemini. If you use Gemini, re-save FilterOrbit > AI Settings with gemini-3.8-flash.
