@blotoutio/providers-evo-search-sdk 1.70.1 → 1.70.2

package/README.md

@@ -26,6 +26,24 @@ export default function Root({ children }) {
 }
 ```
 
+### Multi-market storefronts: pass the market
+
+On a Shopify theme the SDK reads the shopper's currency and country from
+`window.Shopify`. That global does not exist on a headless storefront, so
+without `market` every price renders in the merchant's single configured
+currency (and quick-add validation returns prices for the merchant's default
+market). Pass the market your own router resolved, and pass it again when the
+shopper switches:
+
+```tsx
+<EvoSearchProvider market={{ currency: 'CAD', country: 'CA' }}>{children}</EvoSearchProvider>
+```
+
+It belongs on the provider rather than on a hook: one API object serves every
+EvoSearch surface on the page, so the market is a property of the page — every
+hook picks it up. To set it from a component instead, call
+`useEvoSearchAPI().api?.setMarket({ currency, country })`.
+
 Use the hook in any search component:
 
 ```tsx
@@ -54,6 +72,106 @@ function HeaderSearch() {
 }
 ```
 
+### Full results route
+
+Two options, and the difference matters on a headless storefront:
+
+|                                   | `EvoSearchSearchPage`                 | `useEvoSearchResults`           |
+| --------------------------------- | ------------------------------------- | ------------------------------- |
+| Markup                            | the merchant's published design       | yours                           |
+| Merchant's **Search page** toggle | required — nothing renders without it | ignored; retrieval always works |
+
+**`EvoSearchSearchPage`** renders the managed client-rendered page. It can only
+draw the merchant's published design, so it renders `fallback` whenever that
+design is unavailable — the SDK has not registered, the merchant's results-page
+toggle is off, nothing is published yet, the first search is still in flight, or
+that first search failed. **`fallback` defaults to nothing, so a route with no
+fallback renders blank in every one of those cases.** Always pass your native
+search UI:
+
+```tsx
+import { EvoSearchSearchPage } from '@blotoutio/providers-evo-search-sdk/hooks'
+
+function SearchRoute({ location }: { location: Location }) {
+  return (
+    <EvoSearchSearchPage
+      initialSearch={location.search}
+      onUrlChange={(path) => window.history.replaceState(null, '', path)}
+      fallback={<NativeSearchResults />}
+      // Result tiles otherwise link to the Shopify Online Store URL the catalog
+      // was ingested with — a different domain from a headless storefront.
+      productHref={(product, variantId) => `/products/${product.handle}${variantId ? `?variant=${variantId}` : ''}`}
+      onAddToCart={(product, variantId) => addLine(variantId)}
+    />
+  )
+}
+```
+
+In development it logs which of those reasons applied, once per reason. The v1
+managed page is client-rendered. Pass updated URL-derived state when your router
+handles back/forward navigation.
+
+**`useEvoSearchResults`** is the one to use for a search page you render
+yourself. It provides URL-ready query, filter, sort, pagination, collection,
+loading, and error state while leaving routing and markup under the storefront's
+control. It does **not** wait on the merchant's results-page toggle — that
+setting governs the managed renderer's design, and gating your own markup on it
+would leave your search page silently empty. `searchPageEnabled` is still
+returned if you want to mirror it.
+
+```tsx
+import { parseSearchUrl, useEvoSearchResults } from '@blotoutio/providers-evo-search-sdk/hooks'
+
+function SearchPage({ initialSearch }: { initialSearch: string }) {
+  const initial = parseSearchUrl(initialSearch)
+  const search = useEvoSearchResults({
+    initialQuery: initial.query,
+    initialFilters: initial.filters,
+    initialSort: initial.sort,
+    onUrlChange: (path) => window.history.replaceState(null, '', path),
+  })
+
+  if (!search.ready) return <p>Preparing search…</p>
+  if (search.error) return <p>Search is unavailable. Try again.</p>
+
+  return (
+    <main>
+      <input aria-label='Search products' value={search.query} onChange={(event) => search.setQuery(event.target.value)} />
+      {search.loading && <span>Searching…</span>}
+
+      <select aria-label='Sort products' value={search.sort} onChange={(event) => search.setSort(event.target.value as typeof search.sort)}>
+        <option value='relevance'>Relevance</option>
+        <option value='price-asc'>Price: low to high</option>
+        <option value='price-desc'>Price: high to low</option>
+        <option value='newest'>Newest</option>
+      </select>
+
+      <p aria-live='polite'>{search.totalCount} products</p>
+      <ul>
+        {search.results.map((product) => (
+          <li key={product.id}>
+            <a href={product.url} onClick={() => search.trackClick(product.id)}>
+              {product.title}
+            </a>
+          </li>
+        ))}
+      </ul>
+
+      {search.hasMore && (
+        <button type='button' disabled={search.loadingMore} onClick={search.loadMore}>
+          {search.loadingMore ? 'Loading…' : 'Load more'}
+        </button>
+      )}
+    </main>
+  )
+}
+```
+
+For server-rendered routers, derive the initial state from the request URL and
+pass your router's navigation function as `onUrlChange`. The hook does not
+write to browser history on its own. When the query is cleared, its associated
+filters are cleared too; the shopper's chosen sort is kept.
+
 ## Image search
 
 Shoppers can search with a photo instead of words. The hook exposes it as one extra action that writes the same `results` / `loading` / `error` state as the text path, so you render one result list:
@@ -212,6 +330,16 @@ When you want to render search results with your own React components instead of
 
 The EdgeTag pixel must still be loaded on your storefront for the SDK to register and the React hook to receive an API.
 
+**Leaving this toggle off on a headless storefront is not neutral.** `index.min.js` loads the Lit element, which on a `/search` route tries to inject its own results view into `#ProductGridContainer`, `#product-grid`, `results-list` or `.product-grid-container` — if your app happens to use one of those, it fights React for the same DOM. It also navigates with a full page load instead of your router, reports every request on the `widget` channel so your headless traffic is mislabelled in analytics, and skips the keep-warm ping that only runs in headless mode.
+
+## Headless prerequisites checklist
+
+- **Disable default UI** — on (above).
+- **Product source** — set to `allActive`. The default (`onlineStore`) only syncs products published to the Online Store, which is meaningless on a headless storefront: measured on a live headless tenant, it dropped 56% of the catalog.
+- **Search page** — needed only for `EvoSearchSearchPage`; `useEvoSearchResults` works without it.
+- **EdgeTag loader** — installed on the storefront, not just the Shopify app.
+- **Package version** — the hooks ship from npm, but the API object they call is created by the bundle your tag's worker serves. If the deployed bundle predates a method the hooks need, they log which one; redeploy the tag, or pin the package to the deployed version.
+
 `api.search()` retries transient failures and then rejects with a `TimeoutError` after ~23 seconds rather than hanging, so handle the rejected promise. Pass an `AbortSignal` when a newer query can supersede an older one — it is the only way to cancel pending retries, and the React hook already does this for you.
 
 ## /load endpoint cache