=== Init Live Search ===
Contributors: brokensmile.2103  
Tags: live search, ajax search, instant search, rest api, keyword suggestion  
Requires at least: 5.2  
Tested up to: 6.8  
Requires PHP: 7.4  
Stable tag: 1.4  
License: GPLv2 or later  
License URI: https://www.gnu.org/licenses/gpl-2.0.html  

A blazing-fast live search modal powered by REST API. Built in Vanilla JS. Supports keyboard, voice input, slash commands, and caching.

== Description ==

Give your visitors a lightning-fast search experience — no reloads, no jQuery, no delays. Init Live Search is a modern, fast, and fully keyboard-accessible live search plugin for WordPress.

It replaces the default <input name="s"> with a sleek modal interface that fetches results instantly via the REST API — no jQuery, no page reloads, just instant feedback.
With optional voice input, dark mode, keyword suggestions, and full developer extensibility, it’s perfect for both blogs and advanced headless sites.

When users focus on an <input name="s"> field, a lightweight search modal appears. Results are fetched through the REST API and shown instantly.
The plugin supports:
- Arrow key navigation
- Enter to select
- Escape to close
- Voice input via native browser API

This plugin is part of the [Init Plugin Suite](https://inithtml.com/init-plugin-suite-bo-plugin-wordpress-toi-gian-manh-me-mien-phi/) — a collection of minimalist, fast, and developer-focused tools for WordPress.

== What’s New in Version 1.4 ==

- Slash command support: search using `/recent`, `/popular`, `/category`, `/tag`, `/date`, and `/id`
- Smart `/date` parsing with flexible formats: `Y`, `Y/m`, or `Y/m/d`
- Jump to post by ID instantly using `/id 123`
- Unified command parsing with clean, extensible structure
- Powerful taxonomy and date-based filtering via custom REST endpoints
- Local caching for command results (via `localStorage`)
- Full developer filter support: fallback logic, query args, thumb override, result injection…
- New trigger toggles: enable/disable Ctrl + /, triple-click, or input focus independently
- Code refactor: polished REST API and optimized WP_Query performance

== Features ==

Everything you expect from a modern live search — and more:

- Live search powered by WordPress REST API (no admin-ajax)
- Modern modal interface (no theme override required)
- Fully keyboard accessible (Arrow keys, Enter, Escape)
- Fallback to default search if nothing selected
- Built with pure JavaScript (no jQuery)
- Optional dark mode (.dark class or global config)
- Keyword suggestions (manual or auto-generated)
- Optional result caching via localStorage
- UTM parameter support for link tracking
- Voice input support using SpeechRecognition
- Category filter (client-side only, zero API calls)
- Settings page for fine-grained control (debounce, post types, fallback, etc.)

== Screenshots ==

1. Admin settings with search behavior options
2. Clean modal interface with keyword suggestions
3. Search results with filter pills and post types
4. Fully supports dark mode (auto or manual)

== REST API Endpoints ==

All endpoints are under namespace: `initlise/v1`

- `/search?term=example` — Standard live search query
- `/id/{id}` — Fetch post by ID
- `/recent` — Fetch recent posts (based on settings)
- `/date?value=Y/m/d` — Fetch posts by date
- `/tax?taxonomy=category&term=slug-or-id` — Fetch by taxonomy (e.g., category, tag)

== Installation ==

1. Upload the plugin folder to /wp-content/plugins/ or install via the admin panel.
2. Activate the plugin from the Plugins menu.
3. It will automatically enhance all <input name="s"> fields.
4. (Optional) Configure advanced settings in Settings → Init Live Search.

== Dark Mode Support ==

Enable dark mode for the modal by either:

1. Adding the dark class:
   document.querySelector('#ils-modal')?.classList.add('dark');

2. Or using a global config:
   window.InitPluginSuiteLiveSearchConfig = { theme: 'dark' };

Options: 'dark', 'light', 'auto'

== Admin Settings ==

- Choose post types to include in search
- Set debounce time, max results, and search mode
- Toggle fallback logic (bigrams/trim)
- Enable/disable default CSS
- Enable result caching (localStorage)
- Define or auto-generate keyword suggestions
- Add default UTM parameter to result links

== Keyboard Navigation ==

- Arrow Up/Down — navigate results
- Enter — open selected result or submit
- Escape — close modal and reset state

== Filters for Developers ==

= init_plugin_suite_live_search_enable_fallback =

Enable or disable fallback logic (trimming or bigrams) when few results are found.  
**Applies to:** /search  
Params: bool $enabled, string $term, WP_REST_Request $request

Example:

add_filter( 'init_plugin_suite_live_search_enable_fallback', function ( $enabled, $term, $request ) {
    return false;
}, 10, 3 );

= init_plugin_suite_live_search_post_ids =

Customize the array of post IDs returned from the search query.  
**Applies to:** /search  
Params: array $post_ids, string $term, WP_REST_Request $request

= init_plugin_suite_live_search_result_item =

Modify each result item before it's sent in the response.  
**Applies to:** /search  
Params: array $item, int $post_id, string $term, WP_REST_Request $request

= init_plugin_suite_live_search_results =

Filter the final array of results.  
**Applies to:** /search  
Params: array $results, array $post_ids, string $term, WP_REST_Request $request

= init_plugin_suite_live_search_category =

Customize the category label shown in results.  
**Applies to:** all endpoints  
Params: string $category_name, int $post_id

= init_plugin_suite_live_search_default_thumb =

Override the default thumbnail image if a post has no featured image.  
**Applies to:** all endpoints  
Params: string $thumb_url

= init_plugin_suite_live_search_query_args =

Modify WP_Query arguments for recent, date, or taxonomy-based queries.  
**Applies to:** /recent, /date, /tax  
Params: array $args, string $type ('recent' | 'date' | 'tax'), WP_REST_Request $request

Example:

add_filter( 'init_plugin_suite_live_search_query_args', function ( $args, $type, $request ) {
    if ( $type === 'recent' ) {
        $args['meta_query'][] = [
            'key' => '_custom_flag',
            'value' => 'yes'
        ];
    }
    return $args;
}, 10, 3 );

= init_plugin_suite_live_search_stop_words =

Adjust the stop-word list used when generating keyword suggestions.  
Params: array $stop_words, string $locale


== FAQ ==

= Does this plugin use jQuery? =  
No, it's written in modern Vanilla JavaScript.

= How is search triggered? =  
It automatically detects and overrides <input name="s">.

= Is voice input supported? =  
Yes, via the browser's built-in SpeechRecognition API (if supported).

= Can I generate keyword suggestions automatically? =  
Yes, in the settings panel via a button.

= Is caching enabled by default? =  
No, but you can enable localStorage caching from the admin settings.

= What happens if no result is selected? =  
Fallbacks to default WordPress search behavior.

= Can I use this on mobile? =  
Yes, it's fully responsive and mobile-friendly.

= What’s the triple-click trigger? =  
Click three times rapidly on empty areas to open the modal.

= Can I disable all triggers and only use the REST API? =  
Yes, just turn off all three triggers (input, Ctrl+/, triple-click) in the settings. The plugin will only register the API.

== Changelog ==

= 1.4 – May 23, 2025 =
- Slash command support: search using `/recent`, `/popular`, `/tag`, `/category`, `/date`, and `/id`
- Smart `/date` parsing (supports year, month, and day)
- `/id` command jumps directly to a post by ID
- Unified command parsing and custom REST endpoints
- More powerful taxonomy and date search handling
- Optimized all WP_Query calls for performance
- Internal command result caching (localStorage)
- New option to toggle individual triggers: Ctrl + /, triple-click, or input focus
- Codebase polish and improved JS architecture

= 1.3 – May 22, 2025 =
- Triple-click to open modal
- Keyboard shortcut Ctrl + /
- Display post type name
- Category filter (client-side only)
- Clear icon inside search input
- New developer filter prefix

= 1.2 – May 20, 2025 =
- Voice input (SpeechRecognition)
- Fallback logic and CSS settings
- Developer filters

= 1.1 – May 18, 2025 =
- Improved fallback matching
- Prefill previous term
- Character limit
- UTM and cache support
- Theme control

= 1.0 – May 17, 2025 =
- Initial release
- REST API-powered modal search
- Manual keyword suggestion

== License ==

This plugin is licensed under the GPLv2 or later.  
You are free to use, modify, and distribute it under the same license.