# Codingrow Live Search & Autocomplete — Documentation

Real-time **product autocomplete** for the Magento 2 storefront search bar. As the customer types, a
dropdown shows the matching **products** (image, name, price, discount), each linking straight to the
product page, plus a "see all results" link. This is something Magento Open Source does **not** provide
natively — with Elasticsearch/OpenSearch its native autocomplete only suggests previously-searched
*terms*, never live products. Theme-agnostic: works on **Hyvä and Luma**. Self-hosted, no SaaS, no
recurring cost, no AI/API key required.

---

## Installation

### Requirements
- Magento 2.4.x (Open Source or Adobe Commerce)
- PHP 8.1–8.5
- Any search engine Magento supports (OpenSearch, Elasticsearch or MySQL)
- Hyvä or Luma theme
- The free `codingrow/module-core`

No AI provider or API key is needed — the module is pure catalog search.

### Setup
```
composer require codingrow/module-live-search-autocomplete
bin/magento module:enable Codingrow_LiveSearchAutocomplete
bin/magento setup:upgrade && bin/magento setup:di:compile
bin/magento cache:flush
```
Then go to **Stores → Configuration → Codingrow → Live Search & Autocomplete**, paste your license key,
set **Enable = Yes**, and flush the cache.

### Configuration
All options live under **Stores → Configuration → Codingrow → Live Search & Autocomplete**.

| Setting | What it does | Default |
|---|---|---|
| License Key | The license key issued for this domain. Accepts a single-module key or a Codingrow subscription key. The autocomplete does not render without a valid license. | — |
| Enable | Turns the storefront autocomplete on or off. | No |
| Minimum characters | How many characters the customer must type before suggestions start. | 2 |
| Max products shown | Maximum number of products in the dropdown. | 6 |
| Show product image | Shows the product thumbnail next to each suggestion. | Yes |
| Show price | Shows the price (and any discount) for each suggestion. | Yes |
| Only in-stock products | Hides out-of-stock products from the suggestions. | No |
| Use AI Personal Shopper synonyms | When the AI Personal Shopper module is installed, also use its self-learning synonyms. | Yes |
| Accent color | Color used for prices and the "see all results" link. | #2563eb |

### Uninstall
Set **Enable = No** to switch it off without removing anything, or remove the module entirely:
```
bin/magento module:disable Codingrow_LiveSearchAutocomplete
composer remove codingrow/module-live-search-autocomplete
bin/magento setup:upgrade && bin/magento cache:flush
```

---

## Search & synonyms

### How it works
A small, theme-agnostic script attaches to your existing search input (it detects Hyvä and Luma search
bars automatically). As the customer types, it debounces the input and asks the module for matching
products, then renders a dropdown with a thumbnail, name, price and any discount for each result, plus a
"see all results" link. Every result links straight to the product page. Results respect product
visibility, stock and store scope.

### Performance
Suggestions are fetched from Magento's **own indexed search engine** — the same engine that powers the
results page (OpenSearch, Elasticsearch, or MySQL) — via the native `quick_search_container` request.
Because the matching is done by the index and not by scanning the database, response time stays low and
**does not grow with catalog size**. On a live 67,000-product store, suggestions return in about a second
and stay flat as the catalog grows.

### Extended-field search
Whether the autocomplete searches only the name/SKU or also the description and other fields is controlled
by **Magento itself, per attribute** — not by a module toggle. Under **Stores → Attributes → Product**,
each attribute has a **"Use in Search"** flag and a **search weight**. By default `name`, `sku`,
`description` and `short_description` are searchable, so the autocomplete already searches them. To include
or exclude a field, or make one weigh more, change that attribute's search settings and reindex — the
autocomplete follows the same configuration as the results page, and stays fast regardless of catalog size.

> **Tip:** raise the search weight of the product name so exact name matches always rank above
> description-only matches.

### Native Search Synonyms
The module always uses Magento's native **Search Synonyms**. Add or edit them from the standard admin at
**Marketing → SEO & Search → Search Synonyms**; the autocomplete picks them up immediately. When a query
returns nothing, the module expands it with the matching synonyms and tries again.

### AI Personal Shopper synonyms (optional)
If the [Codingrow AI Personal Shopper](https://codingrow.com/ai-personal-shopper/) module is also installed
(optional, soft dependency), the autocomplete additionally taps its **self-learning synonyms registry** —
the regional, dialect and misspelled terms the assistant has learned from real conversations. This makes
even "wrong" searches match the right products. Turn it on with **Use AI Personal Shopper synonyms = Yes**.
Without that module, the autocomplete works perfectly on the native synonyms alone.

---

## Usage

### How it appears
The dropdown is injected below your existing search bar and styled to stay out of the way of your theme.
Each row shows the product thumbnail (if enabled), the name, and the price with any discount; the accent
color (prices and the "see all results" link) is configurable. Keyboard navigation (arrow keys and Enter)
and mobile layout are handled automatically.

### License
The module uses a **per-domain license** (a single-module key, or a Codingrow subscription key that unlocks
every Codingrow module). The key is verified locally by signature; a revocation check runs at most **once a
day** and is cached, so it never slows the storefront and never exposes your data. The autocomplete does
not render without a valid license. Updates are included within the same major version.

### Troubleshooting

| Symptom | What to check |
|---|---|
| The autocomplete doesn't appear | Make sure **Enable = Yes**, the **License Key** is valid, and you typed at least the minimum number of characters. Then `bin/magento cache:flush`. |
| A product that exists isn't found | Reindex the catalog search index (`bin/magento indexer:reindex catalogsearch_fulltext`) and check the product is visible in search and in stock (if "Only in-stock products" is on). |
| Partial or misspelled words find little | Add native Search Synonyms, or install AI Personal Shopper for automatic learned synonyms. |
| Nothing changed after an update | Run `setup:upgrade`, `setup:di:compile` and `cache:flush` after every `composer update`. |

---

## Changelog
- **1.0.1** — Search now runs through Magento's indexed search engine instead of a direct database query:
  much faster and scalable on large catalogs, with the same partial matching and searchable-attribute
  weights as the results page. No configuration change.
- **1.0.0** — First release: real-time product autocomplete for the Magento 2 search bar, Hyvä and Luma,
  native Search Synonyms plus optional AI Personal Shopper synonyms, and display/appearance options.