@blotoutio/providers-evo-search-sdk 1.52.0 → 1.53.0

package/README.md

@@ -5,3 +5,67 @@ This library was generated with [Nx](https://nx.dev).
 ## Building
 
 Run `nx build providers-evo-search-sdk` to build the library.
+
+## Headless React integration
+
+For headless storefronts (Hydrogen, Next.js, Remix, custom React apps) where the EdgeTag pixel is already installed and the EvoSearch provider is enabled on the tag, this package exports a React hook from the `/hooks` subpath.
+
+Install:
+
+```bash
+npm install @blotoutio/providers-evo-search-sdk
+```
+
+Wrap your app once:
+
+```tsx
+import { EvoSearchProvider } from '@blotoutio/providers-evo-search-sdk/hooks'
+
+export default function Root({ children }) {
+  return <EvoSearchProvider>{children}</EvoSearchProvider>
+}
+```
+
+Use the hook in any search component:
+
+```tsx
+import { useEvoSearch } from '@blotoutio/providers-evo-search-sdk/hooks'
+
+function HeaderSearch() {
+  const { query, setQuery, results, suggestions, loading, trackClick } = useEvoSearch()
+  return (
+    <>
+      <input value={query} onChange={(e) => setQuery(e.target.value)} />
+      {loading && <span>Loading…</span>}
+      <ul>
+        {suggestions.map((s) => (
+          <li key={s.phrase}>{s.phrase}</li>
+        ))}
+      </ul>
+      <ul>
+        {results.map((p) => (
+          <li key={p.id} onClick={() => trackClick(p.id)}>
+            {p.title}
+          </li>
+        ))}
+      </ul>
+    </>
+  )
+}
+```
+
+For full API reference, see the design spec in the Blotout solutions repo or the docs site.
+
+## Disabling the default UI (headless mode)
+
+When you want to render search results with your own React components instead of the default Lit custom element, flip **Disable default UI** in the EvoSearch provider settings (edgetag admin → providers → EvoSearch). With this toggle on:
+
+- The CDN serves a lighter `core.min.js` bundle instead of `index.min.js` — no Lit element, no default DOM.
+- The React hook from the `/hooks` subpath continues to work — it reads the EvoSearch API from the same registry the default UI would have used.
+- Changes take up to 25 minutes to propagate via the edge cache (`max-age=1500` on the `/load` response).
+
+The EdgeTag pixel must still be loaded on your storefront for the SDK to register and the React hook to receive an API.
+
+## /load endpoint cache
+
+CDN responses for `/load` cache for ~25 minutes (`max-age=1500`). Toggling `Disable default UI` in the admin form takes up to that long to propagate across edge nodes — bake the delay into release planning.