@headband/react 0.2.0 → 0.2.1

package/README.md

@@ -167,6 +167,42 @@ Hosted assignment only returns a variant when the rule is `active`, the kill swi
 
 ---
 
+## Click feedback
+
+When click feedback is on for your organization, every search response carries a `queryId`. Send clicks and conversions with it, and Headband counts them per query. Turn on "Use click feedback in ranking" for an index (dashboard or `PATCH /v1/indexes/{uid}/click-feedback`) and results people pick for a query move up for that query. No experiment is needed.
+
+```tsx
+import { useClickTracking, useHits } from "@headband/react";
+
+function Results() {
+  const { hits } = useHits<{ id: string; title: string; url: string }>();
+  const { trackClick } = useClickTracking();
+  return (
+    <ul>
+      {hits.map((hit, i) => (
+        <li key={hit.__data.id}>
+          <a href={hit.__data.url} onClick={() => trackClick(hit, i)}>
+            {hit.__data.title}
+          </a>
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+// Later, on the order page:
+const { trackConversion } = useClickTracking();
+trackConversion(productId, { value: 1999 });
+```
+
+- `trackClick(hit, positionOnPage)` sends the hit's id, the search's `queryId`, its position in the whole result list and a session id. Events are sent with `keepalive`, so a click that opens a new page still arrives.
+- `trackConversion(docId)` names the search the document was last clicked from in this tab.
+- Ids are read from `id`. Set `idField` on `<HeadbandProvider>` if your documents use another field. Set `sessionId` to your own visitor session id; without it, the experiment's session id is used, then an id kept for the browser tab.
+- Outside React: `client.trackClick({ index, docId, queryId, position, sessionId })`, `client.trackConversion({ index, docId, value })` and `client.sendEvents([...])` (up to 100 events).
+- Tracking never throws from the hook. The client methods reject with a `HeadbandError`, as the other calls do.
+
+---
+
 ## Provider
 
 ### `<HeadbandProvider>`
@@ -179,14 +215,15 @@ Wraps your search UI and manages all search state.
 </HeadbandProvider>
 ```
 
-| Prop           | Type                               | Default | Description                                            |
-| -------------- | ---------------------------------- | ------- | ------------------------------------------------------ |
-| `client`       | `HeadbandClient`                   | --      | Client returned by `headband()`                        |
-| `index`        | `string`                           | --      | Index to search                                        |
-| `initialQuery` | `string`                           | `""`    | Starting query value                                   |
-| `experiment`   | `ExperimentSearchMetadata \| null` | `null`  | Optional experiment telemetry attached to search calls |
-| `mode`         | `"instant" \| "retrieval"`         | --      | Visor's ranking mode; other engines ignore it          |
-| `children`     | `ReactNode`                        | --      | Child components                                       |
+| Prop                | Type                               | Default | Description                                                      |
+| ------------------- | ---------------------------------- | ------- | ---------------------------------------------------------------- |
+| `client`            | `HeadbandClient`                   | --      | Client returned by `headband()`                                  |
+| `index`             | `string`                           | --      | Index to search                                                  |
+| `initialQuery`      | `string`                           | `""`    | Starting query value                                             |
+| `experiment`        | `ExperimentSearchMetadata \| null` | `null`  | Optional experiment telemetry attached to search calls           |
+| `mode`              | `"instant" \| "retrieval"`         | --      | Visor's ranking mode; other engines ignore it                    |
+| `disjunctiveFacets` | `boolean`                          | `true`  | Facet lists keep counting their other values after one is ticked |
+| `children`          | `ReactNode`                        | --      | Child components                                                 |
 
 `mode` is also a field of `client.search()` params and of each `client.multiSearch()` query.
 On a Visor index, `instant` (the default) is typo-tolerant, as-you-type search, and
@@ -257,6 +294,12 @@ const { items, refine, canToggle, isLoading } = useRefinementList({
 
 Each `RefinementListItem` has `{ value: string; count: number; isRefined: boolean }`.
 
+Ticking a value does not hide the other values. The provider runs one more search for each facet
+with a ticked value, filtered by everything except that facet's own values, and uses its counts
+for the list. Each of those searches counts as a search on your plan. Pass
+`disjunctiveFacets={false}` to `<HeadbandProvider>` for one search per request; the list then
+shows only the values left in the results. New in 0.2.1: in 0.1.1 and 0.2.0 the list always narrows.
+
 ---
 
 ### `usePagination()`
@@ -410,9 +453,23 @@ const {
 
 All components accept a `styled` prop (default `true`) that toggles built-in Tailwind CSS classes. Set `styled={false}` to bring your own styles.
 
+The built-in styles are Tailwind classes inside this package. Tailwind v4 does not scan
+`node_modules`, so add an `@source` line to the CSS file that imports Tailwind. The path is
+relative to that CSS file. For a Next.js `app/globals.css`:
+
+```css
+@import "tailwindcss";
+@source "../node_modules/@headband/react";
+```
+
+For `src/app/globals.css`, use `"../../node_modules/@headband/react"`.
+
 ### `<SearchBox>`
 
-Search input with built-in clear button and search icon.
+Search input with built-in clear button and search icon. From 0.2.1 it is a text input with
+`role="searchbox"`, so Chrome and Safari add no second clear button. On 0.1.1 and 0.2.0, hide the browser's
+own button with
+`input[type="search"]::-webkit-search-cancel-button { -webkit-appearance: none; }`.
 
 ```tsx
 <SearchBox placeholder="Search products..." autoFocus onQueryChange={(q) => console.log(q)} />

package/dist/index.d.mts

@@ -91,10 +91,50 @@ declare function assignExperiment(config: ExperimentConfig, subjectId: string, o
 }): ExperimentAssignment | null;
 declare function experimentSearchMetadata(assignment: ExperimentAssignment | null | undefined): ExperimentSearchMetadata | undefined;
 
+/**
+ * Search events for click feedback: `search_result_click` and `conversion`.
+ *
+ * A search response carries a `queryId` when click feedback is on for your organization. Send it
+ * with a click so Headband knows which search showed the result. Clicks and conversions are
+ * counted per query; when an index has "Use click feedback in ranking" on, results people pick
+ * for a query move up for that query. No experiment is needed.
+ */
+type SearchEventType = "search_result_click" | "conversion";
+interface SearchEvent {
+    type: SearchEventType;
+    /** The index the result came from. */
+    index: string;
+    /** The clicked or converted document's id (its primary key). */
+    docId: string | number;
+    /** The `queryId` of the search that showed the result. */
+    queryId?: string;
+    /** 1-based position of the result in the whole result list, not just the page. */
+    position?: number;
+    /** A stable id for the visitor's session. Strongly recommended: events without one count half. */
+    sessionId?: string;
+    /** Optional, non-negative: an order value for a conversion. */
+    value?: number;
+}
+type SearchEventRejectReason = "invalid_event" | "invalid_type" | "invalid_index" | "invalid_doc_id" | "invalid_query_id" | "invalid_position" | "invalid_session_id" | "invalid_value" | "index_not_found" | "bot";
+interface SendEventsResponse {
+    accepted: number;
+    /** `index` is the event's position in the array you sent. */
+    rejected: Array<{
+        index: number;
+        reason: SearchEventRejectReason;
+    }>;
+}
+/**
+ * A session id for this browser tab, kept in sessionStorage when it is available and in memory
+ * otherwise. It identifies nothing about the visitor; Headband stores it only as a keyed hash.
+ */
+declare function browserSessionId(): string;
+
 /**
  * Headband search client.
  *
- * Makes requests to the Headband `/v1/search`, `/v1/multi-search` and `/v1/warm` endpoints.
+ * Makes requests to the Headband `/v1/search`, `/v1/multi-search`, `/v1/warm` and
+ * `/v1/relevance/events` endpoints.
  */
 
 /**
@@ -124,6 +164,11 @@ interface SearchParams {
 }
 interface SearchResponse {
     hits: Record<string, unknown>[];
+    /**
+     * The id of this search, `q_` and 16 characters, when click feedback is on for your
+     * organization. Send it with clicks (`trackClick`) so Headband knows which search showed them.
+     */
+    queryId?: string;
     estimatedTotalHits?: number;
     totalHits?: number;
     processingTimeMs: number;
@@ -182,6 +227,15 @@ interface HeadbandClient {
     warm(target: WarmInput, opts?: {
         level?: WarmLevel;
     }): Promise<WarmResponse>;
+    /** Sends up to 100 click and conversion events (POST /v1/relevance/events). */
+    sendEvents(events: SearchEvent[]): Promise<SendEventsResponse>;
+    /**
+     * Records a click on a search result. Pass the search's `queryId`; the client remembers it for
+     * the document so a later `trackConversion` names the same search.
+     */
+    trackClick(event: Omit<SearchEvent, "type">): Promise<SendEventsResponse>;
+    /** Records a conversion (a purchase, a sign-up) of a document found by search. */
+    trackConversion(event: Omit<SearchEvent, "type" | "position">): Promise<SendEventsResponse>;
 }
 declare class HeadbandError extends Error {
     readonly status: number;
@@ -243,11 +297,19 @@ interface SearchActions {
     unregisterFacet: (attribute: string) => void;
     refresh: () => void;
 }
+/** How useClickTracking finds a hit's id and the visitor's session. */
+interface ClickTrackingConfig {
+    /** The field hits carry the document id in. Default `id`. */
+    idField: string;
+    /** The session id events carry; a per-tab id when absent. */
+    sessionId?: string;
+}
 interface HeadbandContextValue {
     client: HeadbandClient;
     index: string;
     state: SearchState;
     actions: SearchActions;
+    tracking: ClickTrackingConfig;
 }
 declare function useHeadbandContext(): HeadbandContextValue;
 interface HeadbandProviderProps {
@@ -266,9 +328,25 @@ interface HeadbandProviderProps {
      * for longer queries). Indexes on the other engines ignore it.
      */
     mode?: SearchMode;
+    /**
+     * Store-style facet counts (default true). With a value ticked in a facet list, that list still
+     * counts its other values, so a shopper can tick a second one. Each facet with a ticked value
+     * costs one more search per request. Set false for one search per request, and lists that narrow
+     * to the ticked values.
+     */
+    disjunctiveFacets?: boolean;
+    /**
+     * The field your documents' ids are in, for click feedback (`useClickTracking`). Default `id`.
+     */
+    idField?: string;
+    /**
+     * A stable id for the visitor's session, sent with click and conversion events. Without it the
+     * experiment's session id is used, else an id kept for this browser tab.
+     */
+    sessionId?: string;
     children: ReactNode;
 }
-declare function HeadbandProvider({ client, index, initialQuery, experiment, baseFilter, mode, children, }: HeadbandProviderProps): react_jsx_runtime.JSX.Element;
+declare function HeadbandProvider({ client, index, initialQuery, experiment, baseFilter, mode, disjunctiveFacets, idField, sessionId, children, }: HeadbandProviderProps): react_jsx_runtime.JSX.Element;
 
 /**
  * Core hook that exposes the full search state and actions.
@@ -436,6 +514,31 @@ interface UseHighlightReturn {
  */
 declare function useHighlight({ hit, attribute, }: UseHighlightProps): UseHighlightReturn;
 
+interface UseClickTrackingReturn {
+    /** The current search's id, when click feedback is on for your organization. */
+    queryId: string | undefined;
+    /**
+     * Records a click on a hit. `positionOnPage` is the hit's 0-based place in the current page;
+     * the absolute position is worked out from the page. Never throws: tracking must not break a
+     * results page, so a failed send resolves to null.
+     */
+    trackClick: (hit: Record<string, unknown>, positionOnPage?: number) => Promise<SendEventsResponse | null>;
+    /**
+     * Records a conversion of a document. It names the search the document was last clicked from
+     * in this tab, unless you pass a `queryId`. Never throws.
+     */
+    trackConversion: (docId: string | number, opts?: {
+        value?: number;
+        queryId?: string;
+    }) => Promise<SendEventsResponse | null>;
+}
+/**
+ * Click feedback events for the provider's index: `search_result_click` and `conversion`. When the
+ * index has "Use click feedback in ranking" on, results people pick for a query move up for that
+ * query.
+ */
+declare function useClickTracking(): UseClickTrackingReturn;
+
 interface SearchBoxProps {
     /** Placeholder text. */
     placeholder?: string;
@@ -576,4 +679,4 @@ interface PoweredByProps {
  */
 declare function PoweredBy({ className, styled, href, }: PoweredByProps): react_jsx_runtime.JSX.Element;
 
-export { type ExperimentAssignment, type ExperimentConfig, type ExperimentConfigQuery, type ExperimentConfigResponse, type ExperimentConfigStatus, type ExperimentConfigsResponse, type ExperimentEventInput, type ExperimentEventResponse, type ExperimentEventType, type ExperimentSearchMetadata, type ExperimentVariantConfig, type FilterInput, type FilterValue, type HeadbandClient, type HeadbandContextValue, HeadbandError, HeadbandProvider, type HeadbandProviderProps, Highlight, type HighlightProps, type Hit, Hits, type HitsProps, type HostedExperimentAssignmentQuery, type HostedExperimentAssignmentResponse, type MultiSearchQuery, type MultiSearchResponse, Pagination, type PaginationProps, PoweredBy, type PoweredByProps, RangeInput, type RangeInputProps, type RangeMap, RefinementList, type RefinementListItem, type RefinementListProps, type RefinementMap, type SearchActions, SearchBox, type SearchBoxProps, type SearchMode, type SearchParams, type SearchResponse, type SearchState, SortBy, type SortByItem, type SortByProps, Stats, type StatsProps, type UseHighlightProps, type UseHighlightReturn, type UseHitsReturn, type UsePaginationReturn, type UseRangeProps, type UseRangeReturn, type UseRefinementListProps, type UseRefinementListReturn, type UseSearchBoxReturn, type UseSortByProps, type UseSortByReturn, type UseStatsReturn, type WarmInput, type WarmLevel, type WarmResponse, andFilters, assignExperiment, buildExperimentConfigPath, chooseExperimentVariant, combineFilters, experimentSearchMetadata, filterEq, filterExists, filterIn, filterNotEq, filterRange, headband, isRunnableExperiment, orFilters, quoteFilterValue, useHeadbandContext, useHighlight, useHits, usePagination, useRange, useRefinementList, useSearch, useSearchBox, useSortBy, useStats };
+export { type ClickTrackingConfig, type ExperimentAssignment, type ExperimentConfig, type ExperimentConfigQuery, type ExperimentConfigResponse, type ExperimentConfigStatus, type ExperimentConfigsResponse, type ExperimentEventInput, type ExperimentEventResponse, type ExperimentEventType, type ExperimentSearchMetadata, type ExperimentVariantConfig, type FilterInput, type FilterValue, type HeadbandClient, type HeadbandContextValue, HeadbandError, HeadbandProvider, type HeadbandProviderProps, Highlight, type HighlightProps, type Hit, Hits, type HitsProps, type HostedExperimentAssignmentQuery, type HostedExperimentAssignmentResponse, type MultiSearchQuery, type MultiSearchResponse, Pagination, type PaginationProps, PoweredBy, type PoweredByProps, RangeInput, type RangeInputProps, type RangeMap, RefinementList, type RefinementListItem, type RefinementListProps, type RefinementMap, type SearchActions, SearchBox, type SearchBoxProps, type SearchEvent, type SearchEventRejectReason, type SearchEventType, type SearchMode, type SearchParams, type SearchResponse, type SearchState, type SendEventsResponse, SortBy, type SortByItem, type SortByProps, Stats, type StatsProps, type UseClickTrackingReturn, type UseHighlightProps, type UseHighlightReturn, type UseHitsReturn, type UsePaginationReturn, type UseRangeProps, type UseRangeReturn, type UseRefinementListProps, type UseRefinementListReturn, type UseSearchBoxReturn, type UseSortByProps, type UseSortByReturn, type UseStatsReturn, type WarmInput, type WarmLevel, type WarmResponse, andFilters, assignExperiment, browserSessionId, buildExperimentConfigPath, chooseExperimentVariant, combineFilters, experimentSearchMetadata, filterEq, filterExists, filterIn, filterNotEq, filterRange, headband, isRunnableExperiment, orFilters, quoteFilterValue, useClickTracking, useHeadbandContext, useHighlight, useHits, usePagination, useRange, useRefinementList, useSearch, useSearchBox, useSortBy, useStats };

package/dist/index.d.ts

@@ -91,10 +91,50 @@ declare function assignExperiment(config: ExperimentConfig, subjectId: string, o
 }): ExperimentAssignment | null;
 declare function experimentSearchMetadata(assignment: ExperimentAssignment | null | undefined): ExperimentSearchMetadata | undefined;
 
+/**
+ * Search events for click feedback: `search_result_click` and `conversion`.
+ *
+ * A search response carries a `queryId` when click feedback is on for your organization. Send it
+ * with a click so Headband knows which search showed the result. Clicks and conversions are
+ * counted per query; when an index has "Use click feedback in ranking" on, results people pick
+ * for a query move up for that query. No experiment is needed.
+ */
+type SearchEventType = "search_result_click" | "conversion";
+interface SearchEvent {
+    type: SearchEventType;
+    /** The index the result came from. */
+    index: string;
+    /** The clicked or converted document's id (its primary key). */
+    docId: string | number;
+    /** The `queryId` of the search that showed the result. */
+    queryId?: string;
+    /** 1-based position of the result in the whole result list, not just the page. */
+    position?: number;
+    /** A stable id for the visitor's session. Strongly recommended: events without one count half. */
+    sessionId?: string;
+    /** Optional, non-negative: an order value for a conversion. */
+    value?: number;
+}
+type SearchEventRejectReason = "invalid_event" | "invalid_type" | "invalid_index" | "invalid_doc_id" | "invalid_query_id" | "invalid_position" | "invalid_session_id" | "invalid_value" | "index_not_found" | "bot";
+interface SendEventsResponse {
+    accepted: number;
+    /** `index` is the event's position in the array you sent. */
+    rejected: Array<{
+        index: number;
+        reason: SearchEventRejectReason;
+    }>;
+}
+/**
+ * A session id for this browser tab, kept in sessionStorage when it is available and in memory
+ * otherwise. It identifies nothing about the visitor; Headband stores it only as a keyed hash.
+ */
+declare function browserSessionId(): string;
+
 /**
  * Headband search client.
  *
- * Makes requests to the Headband `/v1/search`, `/v1/multi-search` and `/v1/warm` endpoints.
+ * Makes requests to the Headband `/v1/search`, `/v1/multi-search`, `/v1/warm` and
+ * `/v1/relevance/events` endpoints.
  */
 
 /**
@@ -124,6 +164,11 @@ interface SearchParams {
 }
 interface SearchResponse {
     hits: Record<string, unknown>[];
+    /**
+     * The id of this search, `q_` and 16 characters, when click feedback is on for your
+     * organization. Send it with clicks (`trackClick`) so Headband knows which search showed them.
+     */
+    queryId?: string;
     estimatedTotalHits?: number;
     totalHits?: number;
     processingTimeMs: number;
@@ -182,6 +227,15 @@ interface HeadbandClient {
     warm(target: WarmInput, opts?: {
         level?: WarmLevel;
     }): Promise<WarmResponse>;
+    /** Sends up to 100 click and conversion events (POST /v1/relevance/events). */
+    sendEvents(events: SearchEvent[]): Promise<SendEventsResponse>;
+    /**
+     * Records a click on a search result. Pass the search's `queryId`; the client remembers it for
+     * the document so a later `trackConversion` names the same search.
+     */
+    trackClick(event: Omit<SearchEvent, "type">): Promise<SendEventsResponse>;
+    /** Records a conversion (a purchase, a sign-up) of a document found by search. */
+    trackConversion(event: Omit<SearchEvent, "type" | "position">): Promise<SendEventsResponse>;
 }
 declare class HeadbandError extends Error {
     readonly status: number;
@@ -243,11 +297,19 @@ interface SearchActions {
     unregisterFacet: (attribute: string) => void;
     refresh: () => void;
 }
+/** How useClickTracking finds a hit's id and the visitor's session. */
+interface ClickTrackingConfig {
+    /** The field hits carry the document id in. Default `id`. */
+    idField: string;
+    /** The session id events carry; a per-tab id when absent. */
+    sessionId?: string;
+}
 interface HeadbandContextValue {
     client: HeadbandClient;
     index: string;
     state: SearchState;
     actions: SearchActions;
+    tracking: ClickTrackingConfig;
 }
 declare function useHeadbandContext(): HeadbandContextValue;
 interface HeadbandProviderProps {
@@ -266,9 +328,25 @@ interface HeadbandProviderProps {
      * for longer queries). Indexes on the other engines ignore it.
      */
     mode?: SearchMode;
+    /**
+     * Store-style facet counts (default true). With a value ticked in a facet list, that list still
+     * counts its other values, so a shopper can tick a second one. Each facet with a ticked value
+     * costs one more search per request. Set false for one search per request, and lists that narrow
+     * to the ticked values.
+     */
+    disjunctiveFacets?: boolean;
+    /**
+     * The field your documents' ids are in, for click feedback (`useClickTracking`). Default `id`.
+     */
+    idField?: string;
+    /**
+     * A stable id for the visitor's session, sent with click and conversion events. Without it the
+     * experiment's session id is used, else an id kept for this browser tab.
+     */
+    sessionId?: string;
     children: ReactNode;
 }
-declare function HeadbandProvider({ client, index, initialQuery, experiment, baseFilter, mode, children, }: HeadbandProviderProps): react_jsx_runtime.JSX.Element;
+declare function HeadbandProvider({ client, index, initialQuery, experiment, baseFilter, mode, disjunctiveFacets, idField, sessionId, children, }: HeadbandProviderProps): react_jsx_runtime.JSX.Element;
 
 /**
  * Core hook that exposes the full search state and actions.
@@ -436,6 +514,31 @@ interface UseHighlightReturn {
  */
 declare function useHighlight({ hit, attribute, }: UseHighlightProps): UseHighlightReturn;
 
+interface UseClickTrackingReturn {
+    /** The current search's id, when click feedback is on for your organization. */
+    queryId: string | undefined;
+    /**
+     * Records a click on a hit. `positionOnPage` is the hit's 0-based place in the current page;
+     * the absolute position is worked out from the page. Never throws: tracking must not break a
+     * results page, so a failed send resolves to null.
+     */
+    trackClick: (hit: Record<string, unknown>, positionOnPage?: number) => Promise<SendEventsResponse | null>;
+    /**
+     * Records a conversion of a document. It names the search the document was last clicked from
+     * in this tab, unless you pass a `queryId`. Never throws.
+     */
+    trackConversion: (docId: string | number, opts?: {
+        value?: number;
+        queryId?: string;
+    }) => Promise<SendEventsResponse | null>;
+}
+/**
+ * Click feedback events for the provider's index: `search_result_click` and `conversion`. When the
+ * index has "Use click feedback in ranking" on, results people pick for a query move up for that
+ * query.
+ */
+declare function useClickTracking(): UseClickTrackingReturn;
+
 interface SearchBoxProps {
     /** Placeholder text. */
     placeholder?: string;
@@ -576,4 +679,4 @@ interface PoweredByProps {
  */
 declare function PoweredBy({ className, styled, href, }: PoweredByProps): react_jsx_runtime.JSX.Element;
 
-export { type ExperimentAssignment, type ExperimentConfig, type ExperimentConfigQuery, type ExperimentConfigResponse, type ExperimentConfigStatus, type ExperimentConfigsResponse, type ExperimentEventInput, type ExperimentEventResponse, type ExperimentEventType, type ExperimentSearchMetadata, type ExperimentVariantConfig, type FilterInput, type FilterValue, type HeadbandClient, type HeadbandContextValue, HeadbandError, HeadbandProvider, type HeadbandProviderProps, Highlight, type HighlightProps, type Hit, Hits, type HitsProps, type HostedExperimentAssignmentQuery, type HostedExperimentAssignmentResponse, type MultiSearchQuery, type MultiSearchResponse, Pagination, type PaginationProps, PoweredBy, type PoweredByProps, RangeInput, type RangeInputProps, type RangeMap, RefinementList, type RefinementListItem, type RefinementListProps, type RefinementMap, type SearchActions, SearchBox, type SearchBoxProps, type SearchMode, type SearchParams, type SearchResponse, type SearchState, SortBy, type SortByItem, type SortByProps, Stats, type StatsProps, type UseHighlightProps, type UseHighlightReturn, type UseHitsReturn, type UsePaginationReturn, type UseRangeProps, type UseRangeReturn, type UseRefinementListProps, type UseRefinementListReturn, type UseSearchBoxReturn, type UseSortByProps, type UseSortByReturn, type UseStatsReturn, type WarmInput, type WarmLevel, type WarmResponse, andFilters, assignExperiment, buildExperimentConfigPath, chooseExperimentVariant, combineFilters, experimentSearchMetadata, filterEq, filterExists, filterIn, filterNotEq, filterRange, headband, isRunnableExperiment, orFilters, quoteFilterValue, useHeadbandContext, useHighlight, useHits, usePagination, useRange, useRefinementList, useSearch, useSearchBox, useSortBy, useStats };
+export { type ClickTrackingConfig, type ExperimentAssignment, type ExperimentConfig, type ExperimentConfigQuery, type ExperimentConfigResponse, type ExperimentConfigStatus, type ExperimentConfigsResponse, type ExperimentEventInput, type ExperimentEventResponse, type ExperimentEventType, type ExperimentSearchMetadata, type ExperimentVariantConfig, type FilterInput, type FilterValue, type HeadbandClient, type HeadbandContextValue, HeadbandError, HeadbandProvider, type HeadbandProviderProps, Highlight, type HighlightProps, type Hit, Hits, type HitsProps, type HostedExperimentAssignmentQuery, type HostedExperimentAssignmentResponse, type MultiSearchQuery, type MultiSearchResponse, Pagination, type PaginationProps, PoweredBy, type PoweredByProps, RangeInput, type RangeInputProps, type RangeMap, RefinementList, type RefinementListItem, type RefinementListProps, type RefinementMap, type SearchActions, SearchBox, type SearchBoxProps, type SearchEvent, type SearchEventRejectReason, type SearchEventType, type SearchMode, type SearchParams, type SearchResponse, type SearchState, type SendEventsResponse, SortBy, type SortByItem, type SortByProps, Stats, type StatsProps, type UseClickTrackingReturn, type UseHighlightProps, type UseHighlightReturn, type UseHitsReturn, type UsePaginationReturn, type UseRangeProps, type UseRangeReturn, type UseRefinementListProps, type UseRefinementListReturn, type UseSearchBoxReturn, type UseSortByProps, type UseSortByReturn, type UseStatsReturn, type WarmInput, type WarmLevel, type WarmResponse, andFilters, assignExperiment, browserSessionId, buildExperimentConfigPath, chooseExperimentVariant, combineFilters, experimentSearchMetadata, filterEq, filterExists, filterIn, filterNotEq, filterRange, headband, isRunnableExperiment, orFilters, quoteFilterValue, useClickTracking, useHeadbandContext, useHighlight, useHits, usePagination, useRange, useRefinementList, useSearch, useSearchBox, useSortBy, useStats };

package/dist/index.js

@@ -34,6 +34,7 @@ __export(index_exports, {
   Stats: () => Stats,
   andFilters: () => andFilters,
   assignExperiment: () => assignExperiment,
+  browserSessionId: () => browserSessionId,
   buildExperimentConfigPath: () => buildExperimentConfigPath,
   chooseExperimentVariant: () => chooseExperimentVariant,
   combineFilters: () => combineFilters,
@@ -47,6 +48,7 @@ __export(index_exports, {
   isRunnableExperiment: () => isRunnableExperiment,
   orFilters: () => orFilters,
   quoteFilterValue: () => quoteFilterValue,
+  useClickTracking: () => useClickTracking,
   useHeadbandContext: () => useHeadbandContext,
   useHighlight: () => useHighlight,
   useHits: () => useHits,
@@ -124,6 +126,69 @@ function experimentSearchMetadata(assignment) {
   };
 }
 
+// src/events.ts
+var SESSION_KEY = "headband.sessionId";
+var CLICKS_KEY = "headband.clickedQueries";
+var CLICKS_MAX = 50;
+var memorySession = null;
+var memoryClicks = [];
+function randomId() {
+  const c = globalThis.crypto;
+  if (c?.randomUUID) return `s_${c.randomUUID().replace(/-/g, "").slice(0, 20)}`;
+  return `s_${Math.random().toString(36).slice(2)}${Math.random().toString(36).slice(2)}`.slice(
+    0,
+    22
+  );
+}
+function storage() {
+  try {
+    return typeof sessionStorage === "undefined" ? null : sessionStorage;
+  } catch {
+    return null;
+  }
+}
+function browserSessionId() {
+  const s = storage();
+  try {
+    const stored = s?.getItem(SESSION_KEY);
+    if (stored) return stored;
+  } catch {
+  }
+  if (!memorySession) memorySession = randomId();
+  try {
+    s?.setItem(SESSION_KEY, memorySession);
+  } catch {
+  }
+  return memorySession;
+}
+function readClicks() {
+  const s = storage();
+  try {
+    const raw = s?.getItem(CLICKS_KEY);
+    if (raw) {
+      const parsed = JSON.parse(raw);
+      if (Array.isArray(parsed)) return parsed;
+    }
+  } catch {
+  }
+  return memoryClicks;
+}
+function rememberClick(index, docId, queryId) {
+  const k = `${index}
+${String(docId)}`;
+  const next = [...readClicks().filter(([key]) => key !== k), [k, queryId]];
+  memoryClicks = next.slice(-CLICKS_MAX);
+  try {
+    storage()?.setItem(CLICKS_KEY, JSON.stringify(memoryClicks));
+  } catch {
+  }
+}
+function clickedFrom(index, docId) {
+  const k = `${index}
+${String(docId)}`;
+  return readClicks().find(([key]) => key === k)?.[1];
+}
+
 // src/client.ts
 var HeadbandError = class extends Error {
   constructor(message, status, code) {
@@ -145,7 +210,9 @@ function headband(host, apiKey) {
           ...method === "POST" ? { "Content-Type": "application/json" } : {},
           Authorization: `Bearer ${apiKey}`
         },
-        ...method === "POST" ? { body: JSON.stringify(options.body ?? {}) } : {}
+        ...method === "POST" ? { body: JSON.stringify(options.body ?? {}) } : {},
+        // An event sent as the page navigates away (a click on a result link) still arrives.
+        ...options.keepalive ? { keepalive: true } : {}
       });
     } catch (err) {
       throw new HeadbandError(err instanceof Error ? err.message : "Network request failed", 0);
@@ -207,8 +274,23 @@ function headband(host, apiKey) {
       return request("/v1/warm", {
         body: { ...target, ...opts?.level ? { level: opts.level } : {} }
       });
+    },
+    sendEvents,
+    trackClick(event) {
+      if (event.queryId) rememberClick(event.index, event.docId, event.queryId);
+      return sendEvents([{ type: "search_result_click", ...event }]);
+    },
+    trackConversion(event) {
+      const queryId = event.queryId ?? clickedFrom(event.index, event.docId);
+      return sendEvents([{ type: "conversion", ...event, ...queryId ? { queryId } : {} }]);
     }
   };
+  function sendEvents(events) {
+    return request("/v1/relevance/events", {
+      body: { events },
+      keepalive: true
+    });
+  }
 }
 
 // src/filters.ts
@@ -297,6 +379,40 @@ function buildFilterString(refinements, ranges) {
   });
   return parts.length > 0 ? parts.join(" AND ") : void 0;
 }
+function facetCountQueries(facets, refinements, ranges, baseFilter) {
+  const queries = [];
+  facets.forEach((attribute) => {
+    if ((refinements.get(attribute)?.size ?? 0) === 0) return;
+    const others = new Map(refinements);
+    others.delete(attribute);
+    queries.push({
+      attribute,
+      filter: combineFilters(baseFilter, buildFilterString(others, ranges))
+    });
+  });
+  return queries;
+}
+async function searchWithFacetCounts(client, index, query, params, countQueries) {
+  const [main, ...counts] = await Promise.all([
+    client.search(index, query, params),
+    ...countQueries.map(
+      (cq) => client.search(index, query, {
+        // One hit is the least every engine accepts. Only the counts are read.
+        limit: 1,
+        facets: [cq.attribute],
+        ...cq.filter ? { filter: cq.filter } : {},
+        ...params.mode ? { mode: params.mode } : {}
+      }).catch(() => null)
+    )
+  ]);
+  if (countQueries.length === 0) return main;
+  const facetDistribution = { ...main.facetDistribution ?? {} };
+  countQueries.forEach((cq, i) => {
+    const counted = counts[i]?.facetDistribution?.[cq.attribute];
+    if (counted) facetDistribution[cq.attribute] = counted;
+  });
+  return { ...main, facetDistribution };
+}
 function HeadbandProvider({
   client,
   index,
@@ -304,6 +420,9 @@ function HeadbandProvider({
   experiment = null,
   baseFilter,
   mode,
+  disjunctiveFacets = true,
+  idField = "id",
+  sessionId,
   children
 }) {
   const [query, setQueryRaw] = (0, import_react.useState)(initialQuery);
@@ -341,7 +460,8 @@ function HeadbandProvider({
       ...mode ? { mode } : {},
       attributesToHighlight: ["*"]
     };
-    client.search(index, query, params).then((res) => {
+    const countQueries = disjunctiveFacets ? facetCountQueries(facets, refinements, ranges, baseFilter) : [];
+    searchWithFacetCounts(client, index, query, params, countQueries).then((res) => {
       if (requestId !== requestIdRef.current) {
         return;
       }
@@ -354,7 +474,23 @@ function HeadbandProvider({
       setError(err instanceof Error ? err : new Error(String(err)));
       setIsLoading(false);
     });
-  }, [client, index, query, filter, facetList, sortList, experiment, mode, page, hitsPerPage]);
+  }, [
+    client,
+    index,
+    query,
+    filter,
+    facetList,
+    sortList,
+    experiment,
+    mode,
+    page,
+    hitsPerPage,
+    disjunctiveFacets,
+    facets,
+    refinements,
+    ranges,
+    baseFilter
+  ]);
   (0, import_react.useEffect)(() => {
     const timer = setTimeout(executeSearch, 200);
     return () => {
@@ -411,9 +547,13 @@ function HeadbandProvider({
       return next;
     });
   }, []);
-  const refresh = (0, import_react.useCallback)(() => {
-    executeSearch();
+  const executeSearchRef = (0, import_react.useRef)(executeSearch);
+  (0, import_react.useEffect)(() => {
+    executeSearchRef.current = executeSearch;
   }, [executeSearch]);
+  const refresh = (0, import_react.useCallback)(() => {
+    executeSearchRef.current();
+  }, []);
   const state = (0, import_react.useMemo)(
     () => ({
       query,
@@ -455,9 +595,14 @@ function HeadbandProvider({
       refresh
     ]
   );
+  const trackingSessionId = sessionId ?? experiment?.sessionId;
+  const tracking = (0, import_react.useMemo)(
+    () => ({ idField, ...trackingSessionId ? { sessionId: trackingSessionId } : {} }),
+    [idField, trackingSessionId]
+  );
   const value = (0, import_react.useMemo)(
-    () => ({ client, index, state, actions }),
-    [client, index, state, actions]
+    () => ({ client, index, state, actions, tracking }),
+    [client, index, state, actions, tracking]
   );
   return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(HeadbandContext.Provider, { value, children });
 }
@@ -708,8 +853,41 @@ function useHighlight({
   }, [hit, attribute]);
 }
 
-// src/components/SearchBox.tsx
+// src/hooks/useClickTracking.ts
 var import_react10 = require("react");
+function useClickTracking() {
+  const { client, index, state, tracking } = useHeadbandContext();
+  const queryId = state.results?.queryId;
+  const { page, hitsPerPage } = state;
+  const trackClick = (0, import_react10.useCallback)(
+    (hit, positionOnPage) => {
+      const raw = hit[tracking.idField] ?? hit.__data?.[tracking.idField];
+      if (typeof raw !== "string" && typeof raw !== "number") return Promise.resolve(null);
+      const position = typeof positionOnPage === "number" && positionOnPage >= 0 ? page * hitsPerPage + positionOnPage + 1 : void 0;
+      return client.trackClick({
+        index,
+        docId: raw,
+        ...queryId ? { queryId } : {},
+        ...position ? { position } : {},
+        sessionId: tracking.sessionId ?? browserSessionId()
+      }).catch(() => null);
+    },
+    [client, index, queryId, page, hitsPerPage, tracking]
+  );
+  const trackConversion = (0, import_react10.useCallback)(
+    (docId, opts = {}) => client.trackConversion({
+      index,
+      docId,
+      sessionId: tracking.sessionId ?? browserSessionId(),
+      ...opts
+    }).catch(() => null),
+    [client, index, tracking]
+  );
+  return { queryId, trackClick, trackConversion };
+}
+
+// src/components/SearchBox.tsx
+var import_react11 = require("react");
 var import_jsx_runtime2 = require("react/jsx-runtime");
 function SearchBox({
   placeholder = "Search...",
@@ -719,8 +897,8 @@ function SearchBox({
   styled = true
 }) {
   const { query, setQuery, clear } = useSearchBox();
-  const inputRef = (0, import_react10.useRef)(null);
-  const handleChange = (0, import_react10.useCallback)(
+  const inputRef = (0, import_react11.useRef)(null);
+  const handleChange = (0, import_react11.useCallback)(
     (e) => {
       const value = e.target.value;
       setQuery(value);
@@ -728,15 +906,15 @@ function SearchBox({
     },
     [setQuery, onQueryChange]
   );
-  const handleClear = (0, import_react10.useCallback)(() => {
+  const handleClear = (0, import_react11.useCallback)(() => {
     clear();
     onQueryChange?.("");
     inputRef.current?.focus();
   }, [clear, onQueryChange]);
-  const handleSubmit = (0, import_react10.useCallback)((e) => {
+  const handleSubmit = (0, import_react11.useCallback)((e) => {
     e.preventDefault();
   }, []);
-  const handleKeyDown = (0, import_react10.useCallback)(
+  const handleKeyDown = (0, import_react11.useCallback)(
     (e) => {
       if (e.key === "Escape") {
         handleClear();
@@ -777,7 +955,10 @@ function SearchBox({
           "input",
           {
             ref: inputRef,
-            type: "search",
+            type: "text",
+            role: "searchbox",
+            inputMode: "search",
+            enterKeyHint: "search",
             value: query,
             onChange: handleChange,
             onKeyDown: handleKeyDown,
@@ -807,14 +988,7 @@ function SearchBox({
                 stroke: "currentColor",
                 className: "h-3.5 w-3.5",
                 "aria-hidden": "true",
-                children: /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
-                  "path",
-                  {
-                    strokeLinecap: "round",
-                    strokeLinejoin: "round",
-                    d: "M6 18 18 6M6 6l12 12"
-                  }
-                )
+                children: /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("path", { strokeLinecap: "round", strokeLinejoin: "round", d: "M6 18 18 6M6 6l12 12" })
               }
             )
           }
@@ -876,7 +1050,7 @@ function Hits({
 }
 
 // src/components/RefinementList.tsx
-var import_react11 = require("react");
+var import_react12 = require("react");
 var import_jsx_runtime4 = require("react/jsx-runtime");
 function RefinementList({
   attribute,
@@ -891,7 +1065,7 @@ function RefinementList({
     limit,
     sortBy
   });
-  const handleChange = (0, import_react11.useCallback)(
+  const handleChange = (0, import_react12.useCallback)(
     (value) => () => {
       refine(value);
     },
@@ -951,14 +1125,14 @@ function RefinementList({
 }
 
 // src/components/Pagination.tsx
-var import_react12 = require("react");
+var import_react13 = require("react");
 var import_jsx_runtime5 = require("react/jsx-runtime");
 function Pagination({ className, styled = true }) {
   const { currentPage, totalPages, setPage, canPrevious, canNext, pages } = usePagination();
-  const handlePrevious = (0, import_react12.useCallback)(() => {
+  const handlePrevious = (0, import_react13.useCallback)(() => {
     setPage(currentPage - 1);
   }, [setPage, currentPage]);
-  const handleNext = (0, import_react12.useCallback)(() => {
+  const handleNext = (0, import_react13.useCallback)(() => {
     setPage(currentPage + 1);
   }, [setPage, currentPage]);
   if (totalPages <= 1) return null;
@@ -1061,7 +1235,7 @@ function Stats({ className, styled = true, render }) {
 }
 
 // src/components/SortBy.tsx
-var import_react13 = require("react");
+var import_react14 = require("react");
 var import_jsx_runtime7 = require("react/jsx-runtime");
 function SortBy({
   items: itemsProp,
@@ -1070,7 +1244,7 @@ function SortBy({
   label = "Sort by"
 }) {
   const { currentSort, setSort, items } = useSortBy({ items: itemsProp });
-  const handleChange = (0, import_react13.useCallback)(
+  const handleChange = (0, import_react14.useCallback)(
     (e) => {
       const value = e.target.value;
       setSort(value === "" ? null : value);
@@ -1121,7 +1295,7 @@ function Highlight({
 }
 
 // src/components/RangeInput.tsx
-var import_react14 = require("react");
+var import_react15 = require("react");
 var import_jsx_runtime9 = require("react/jsx-runtime");
 function RangeInput({
   attribute,
@@ -1135,7 +1309,7 @@ function RangeInput({
   const defaultMin = min !== void 0 ? String(min) : "";
   const defaultMax = max !== void 0 ? String(max) : "";
   const formKey = `${attribute}:${defaultMin}:${defaultMax}`;
-  const handleSubmit = (0, import_react14.useCallback)(
+  const handleSubmit = (0, import_react15.useCallback)(
     (e) => {
       e.preventDefault();
       const formData = new FormData(e.currentTarget);
@@ -1281,6 +1455,7 @@ function PoweredBy({
   Stats,
   andFilters,
   assignExperiment,
+  browserSessionId,
   buildExperimentConfigPath,
   chooseExperimentVariant,
   combineFilters,
@@ -1294,6 +1469,7 @@ function PoweredBy({
   isRunnableExperiment,
   orFilters,
   quoteFilterValue,
+  useClickTracking,
   useHeadbandContext,
   useHighlight,
   useHits,

package/dist/index.mjs

@@ -64,6 +64,69 @@ function experimentSearchMetadata(assignment) {
   };
 }
 
+// src/events.ts
+var SESSION_KEY = "headband.sessionId";
+var CLICKS_KEY = "headband.clickedQueries";
+var CLICKS_MAX = 50;
+var memorySession = null;
+var memoryClicks = [];
+function randomId() {
+  const c = globalThis.crypto;
+  if (c?.randomUUID) return `s_${c.randomUUID().replace(/-/g, "").slice(0, 20)}`;
+  return `s_${Math.random().toString(36).slice(2)}${Math.random().toString(36).slice(2)}`.slice(
+    0,
+    22
+  );
+}
+function storage() {
+  try {
+    return typeof sessionStorage === "undefined" ? null : sessionStorage;
+  } catch {
+    return null;
+  }
+}
+function browserSessionId() {
+  const s = storage();
+  try {
+    const stored = s?.getItem(SESSION_KEY);
+    if (stored) return stored;
+  } catch {
+  }
+  if (!memorySession) memorySession = randomId();
+  try {
+    s?.setItem(SESSION_KEY, memorySession);
+  } catch {
+  }
+  return memorySession;
+}
+function readClicks() {
+  const s = storage();
+  try {
+    const raw = s?.getItem(CLICKS_KEY);
+    if (raw) {
+      const parsed = JSON.parse(raw);
+      if (Array.isArray(parsed)) return parsed;
+    }
+  } catch {
+  }
+  return memoryClicks;
+}
+function rememberClick(index, docId, queryId) {
+  const k = `${index}
+${String(docId)}`;
+  const next = [...readClicks().filter(([key]) => key !== k), [k, queryId]];
+  memoryClicks = next.slice(-CLICKS_MAX);
+  try {
+    storage()?.setItem(CLICKS_KEY, JSON.stringify(memoryClicks));
+  } catch {
+  }
+}
+function clickedFrom(index, docId) {
+  const k = `${index}
+${String(docId)}`;
+  return readClicks().find(([key]) => key === k)?.[1];
+}
+
 // src/client.ts
 var HeadbandError = class extends Error {
   constructor(message, status, code) {
@@ -85,7 +148,9 @@ function headband(host, apiKey) {
           ...method === "POST" ? { "Content-Type": "application/json" } : {},
           Authorization: `Bearer ${apiKey}`
         },
-        ...method === "POST" ? { body: JSON.stringify(options.body ?? {}) } : {}
+        ...method === "POST" ? { body: JSON.stringify(options.body ?? {}) } : {},
+        // An event sent as the page navigates away (a click on a result link) still arrives.
+        ...options.keepalive ? { keepalive: true } : {}
       });
     } catch (err) {
       throw new HeadbandError(err instanceof Error ? err.message : "Network request failed", 0);
@@ -147,8 +212,23 @@ function headband(host, apiKey) {
       return request("/v1/warm", {
         body: { ...target, ...opts?.level ? { level: opts.level } : {} }
       });
+    },
+    sendEvents,
+    trackClick(event) {
+      if (event.queryId) rememberClick(event.index, event.docId, event.queryId);
+      return sendEvents([{ type: "search_result_click", ...event }]);
+    },
+    trackConversion(event) {
+      const queryId = event.queryId ?? clickedFrom(event.index, event.docId);
+      return sendEvents([{ type: "conversion", ...event, ...queryId ? { queryId } : {} }]);
     }
   };
+  function sendEvents(events) {
+    return request("/v1/relevance/events", {
+      body: { events },
+      keepalive: true
+    });
+  }
 }
 
 // src/filters.ts
@@ -245,6 +325,40 @@ function buildFilterString(refinements, ranges) {
   });
   return parts.length > 0 ? parts.join(" AND ") : void 0;
 }
+function facetCountQueries(facets, refinements, ranges, baseFilter) {
+  const queries = [];
+  facets.forEach((attribute) => {
+    if ((refinements.get(attribute)?.size ?? 0) === 0) return;
+    const others = new Map(refinements);
+    others.delete(attribute);
+    queries.push({
+      attribute,
+      filter: combineFilters(baseFilter, buildFilterString(others, ranges))
+    });
+  });
+  return queries;
+}
+async function searchWithFacetCounts(client, index, query, params, countQueries) {
+  const [main, ...counts] = await Promise.all([
+    client.search(index, query, params),
+    ...countQueries.map(
+      (cq) => client.search(index, query, {
+        // One hit is the least every engine accepts. Only the counts are read.
+        limit: 1,
+        facets: [cq.attribute],
+        ...cq.filter ? { filter: cq.filter } : {},
+        ...params.mode ? { mode: params.mode } : {}
+      }).catch(() => null)
+    )
+  ]);
+  if (countQueries.length === 0) return main;
+  const facetDistribution = { ...main.facetDistribution ?? {} };
+  countQueries.forEach((cq, i) => {
+    const counted = counts[i]?.facetDistribution?.[cq.attribute];
+    if (counted) facetDistribution[cq.attribute] = counted;
+  });
+  return { ...main, facetDistribution };
+}
 function HeadbandProvider({
   client,
   index,
@@ -252,6 +366,9 @@ function HeadbandProvider({
   experiment = null,
   baseFilter,
   mode,
+  disjunctiveFacets = true,
+  idField = "id",
+  sessionId,
   children
 }) {
   const [query, setQueryRaw] = useState(initialQuery);
@@ -289,7 +406,8 @@ function HeadbandProvider({
       ...mode ? { mode } : {},
       attributesToHighlight: ["*"]
     };
-    client.search(index, query, params).then((res) => {
+    const countQueries = disjunctiveFacets ? facetCountQueries(facets, refinements, ranges, baseFilter) : [];
+    searchWithFacetCounts(client, index, query, params, countQueries).then((res) => {
       if (requestId !== requestIdRef.current) {
         return;
       }
@@ -302,7 +420,23 @@ function HeadbandProvider({
       setError(err instanceof Error ? err : new Error(String(err)));
       setIsLoading(false);
     });
-  }, [client, index, query, filter, facetList, sortList, experiment, mode, page, hitsPerPage]);
+  }, [
+    client,
+    index,
+    query,
+    filter,
+    facetList,
+    sortList,
+    experiment,
+    mode,
+    page,
+    hitsPerPage,
+    disjunctiveFacets,
+    facets,
+    refinements,
+    ranges,
+    baseFilter
+  ]);
   useEffect(() => {
     const timer = setTimeout(executeSearch, 200);
     return () => {
@@ -359,9 +493,13 @@ function HeadbandProvider({
       return next;
     });
   }, []);
-  const refresh = useCallback(() => {
-    executeSearch();
+  const executeSearchRef = useRef(executeSearch);
+  useEffect(() => {
+    executeSearchRef.current = executeSearch;
   }, [executeSearch]);
+  const refresh = useCallback(() => {
+    executeSearchRef.current();
+  }, []);
   const state = useMemo(
     () => ({
       query,
@@ -403,9 +541,14 @@ function HeadbandProvider({
       refresh
     ]
   );
+  const trackingSessionId = sessionId ?? experiment?.sessionId;
+  const tracking = useMemo(
+    () => ({ idField, ...trackingSessionId ? { sessionId: trackingSessionId } : {} }),
+    [idField, trackingSessionId]
+  );
   const value = useMemo(
-    () => ({ client, index, state, actions }),
-    [client, index, state, actions]
+    () => ({ client, index, state, actions, tracking }),
+    [client, index, state, actions, tracking]
   );
   return /* @__PURE__ */ jsx(HeadbandContext.Provider, { value, children });
 }
@@ -656,11 +799,41 @@ function useHighlight({
   }, [hit, attribute]);
 }
 
+// src/hooks/useClickTracking.ts
+import { useCallback as useCallback7 } from "react";
+function useClickTracking() {
+  const { client, index, state, tracking } = useHeadbandContext();
+  const queryId = state.results?.queryId;
+  const { page, hitsPerPage } = state;
+  const trackClick = useCallback7(
+    (hit, positionOnPage) => {
+      const raw = hit[tracking.idField] ?? hit.__data?.[tracking.idField];
+      if (typeof raw !== "string" && typeof raw !== "number") return Promise.resolve(null);
+      const position = typeof positionOnPage === "number" && positionOnPage >= 0 ? page * hitsPerPage + positionOnPage + 1 : void 0;
+      return client.trackClick({
+        index,
+        docId: raw,
+        ...queryId ? { queryId } : {},
+        ...position ? { position } : {},
+        sessionId: tracking.sessionId ?? browserSessionId()
+      }).catch(() => null);
+    },
+    [client, index, queryId, page, hitsPerPage, tracking]
+  );
+  const trackConversion = useCallback7(
+    (docId, opts = {}) => client.trackConversion({
+      index,
+      docId,
+      sessionId: tracking.sessionId ?? browserSessionId(),
+      ...opts
+    }).catch(() => null),
+    [client, index, tracking]
+  );
+  return { queryId, trackClick, trackConversion };
+}
+
 // src/components/SearchBox.tsx
-import {
-  useCallback as useCallback7,
-  useRef as useRef2
-} from "react";
+import { useCallback as useCallback8, useRef as useRef2 } from "react";
 import { jsx as jsx2, jsxs } from "react/jsx-runtime";
 function SearchBox({
   placeholder = "Search...",
@@ -671,7 +844,7 @@ function SearchBox({
 }) {
   const { query, setQuery, clear } = useSearchBox();
   const inputRef = useRef2(null);
-  const handleChange = useCallback7(
+  const handleChange = useCallback8(
     (e) => {
       const value = e.target.value;
       setQuery(value);
@@ -679,15 +852,15 @@ function SearchBox({
     },
     [setQuery, onQueryChange]
   );
-  const handleClear = useCallback7(() => {
+  const handleClear = useCallback8(() => {
     clear();
     onQueryChange?.("");
     inputRef.current?.focus();
   }, [clear, onQueryChange]);
-  const handleSubmit = useCallback7((e) => {
+  const handleSubmit = useCallback8((e) => {
     e.preventDefault();
   }, []);
-  const handleKeyDown = useCallback7(
+  const handleKeyDown = useCallback8(
     (e) => {
       if (e.key === "Escape") {
         handleClear();
@@ -728,7 +901,10 @@ function SearchBox({
           "input",
           {
             ref: inputRef,
-            type: "search",
+            type: "text",
+            role: "searchbox",
+            inputMode: "search",
+            enterKeyHint: "search",
             value: query,
             onChange: handleChange,
             onKeyDown: handleKeyDown,
@@ -758,14 +934,7 @@ function SearchBox({
                 stroke: "currentColor",
                 className: "h-3.5 w-3.5",
                 "aria-hidden": "true",
-                children: /* @__PURE__ */ jsx2(
-                  "path",
-                  {
-                    strokeLinecap: "round",
-                    strokeLinejoin: "round",
-                    d: "M6 18 18 6M6 6l12 12"
-                  }
-                )
+                children: /* @__PURE__ */ jsx2("path", { strokeLinecap: "round", strokeLinejoin: "round", d: "M6 18 18 6M6 6l12 12" })
               }
             )
           }
@@ -827,7 +996,7 @@ function Hits({
 }
 
 // src/components/RefinementList.tsx
-import { useCallback as useCallback8 } from "react";
+import { useCallback as useCallback9 } from "react";
 import { jsx as jsx4, jsxs as jsxs3 } from "react/jsx-runtime";
 function RefinementList({
   attribute,
@@ -842,7 +1011,7 @@ function RefinementList({
     limit,
     sortBy
   });
-  const handleChange = useCallback8(
+  const handleChange = useCallback9(
     (value) => () => {
       refine(value);
     },
@@ -902,14 +1071,14 @@ function RefinementList({
 }
 
 // src/components/Pagination.tsx
-import { useCallback as useCallback9 } from "react";
+import { useCallback as useCallback10 } from "react";
 import { jsx as jsx5, jsxs as jsxs4 } from "react/jsx-runtime";
 function Pagination({ className, styled = true }) {
   const { currentPage, totalPages, setPage, canPrevious, canNext, pages } = usePagination();
-  const handlePrevious = useCallback9(() => {
+  const handlePrevious = useCallback10(() => {
     setPage(currentPage - 1);
   }, [setPage, currentPage]);
-  const handleNext = useCallback9(() => {
+  const handleNext = useCallback10(() => {
     setPage(currentPage + 1);
   }, [setPage, currentPage]);
   if (totalPages <= 1) return null;
@@ -1012,7 +1181,7 @@ function Stats({ className, styled = true, render }) {
 }
 
 // src/components/SortBy.tsx
-import { useCallback as useCallback10 } from "react";
+import { useCallback as useCallback11 } from "react";
 import { jsx as jsx7, jsxs as jsxs5 } from "react/jsx-runtime";
 function SortBy({
   items: itemsProp,
@@ -1021,7 +1190,7 @@ function SortBy({
   label = "Sort by"
 }) {
   const { currentSort, setSort, items } = useSortBy({ items: itemsProp });
-  const handleChange = useCallback10(
+  const handleChange = useCallback11(
     (e) => {
       const value = e.target.value;
       setSort(value === "" ? null : value);
@@ -1072,7 +1241,7 @@ function Highlight({
 }
 
 // src/components/RangeInput.tsx
-import { useCallback as useCallback11 } from "react";
+import { useCallback as useCallback12 } from "react";
 import { jsx as jsx9, jsxs as jsxs6 } from "react/jsx-runtime";
 function RangeInput({
   attribute,
@@ -1086,7 +1255,7 @@ function RangeInput({
   const defaultMin = min !== void 0 ? String(min) : "";
   const defaultMax = max !== void 0 ? String(max) : "";
   const formKey = `${attribute}:${defaultMin}:${defaultMax}`;
-  const handleSubmit = useCallback11(
+  const handleSubmit = useCallback12(
     (e) => {
       e.preventDefault();
       const formData = new FormData(e.currentTarget);
@@ -1231,6 +1400,7 @@ export {
   Stats,
   andFilters,
   assignExperiment,
+  browserSessionId,
   buildExperimentConfigPath,
   chooseExperimentVariant,
   combineFilters,
@@ -1244,6 +1414,7 @@ export {
   isRunnableExperiment,
   orFilters,
   quoteFilterValue,
+  useClickTracking,
   useHeadbandContext,
   useHighlight,
   useHits,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@headband/react",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "React hooks and components for Headband search — an InstantSearch-inspired SDK",
   "main": "dist/index.js",
   "module": "dist/index.mjs",