@headband/react 0.1.1 → 0.2.0

package/dist/index.mjs

@@ -1,5 +1,69 @@
 "use client";
 
+// src/experiments.ts
+function stableHash(input) {
+  let hash = 2166136261;
+  for (let i = 0; i < input.length; i += 1) {
+    hash ^= input.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return hash >>> 0;
+}
+function bucket(input, max) {
+  if (max <= 0) return 0;
+  return stableHash(input) % max;
+}
+function assignmentSeed(config, subjectId, scope) {
+  return `${config.assignmentSalt || config.experimentKey}:${config.experimentKey}:${scope}:${subjectId}`;
+}
+function buildExperimentConfigPath(query = {}) {
+  const params = new URLSearchParams();
+  if (query.projectId) params.set("projectId", query.projectId);
+  if (query.indexUid) params.set("indexUid", query.indexUid);
+  if (query.experimentKey) params.set("experimentKey", query.experimentKey);
+  const search = params.toString();
+  return `/v1/experiments/config${search ? `?${search}` : ""}`;
+}
+function isRunnableExperiment(config) {
+  return config.status === "active" && !config.killSwitch && config.trafficPercent > 0 && config.variants.length > 0;
+}
+function chooseExperimentVariant(config, subjectId) {
+  if (!isRunnableExperiment(config)) return null;
+  const trafficBucket = bucket(assignmentSeed(config, subjectId, "traffic"), 1e4) / 100;
+  if (trafficBucket >= config.trafficPercent) return null;
+  const totalWeight = config.variants.reduce(
+    (sum, variant) => sum + Math.max(0, variant.weight),
+    0
+  );
+  if (totalWeight <= 0) return null;
+  const variantBucket = bucket(assignmentSeed(config, subjectId, "variant"), totalWeight);
+  let cursor = 0;
+  for (const variant of config.variants) {
+    cursor += Math.max(0, variant.weight);
+    if (variantBucket < cursor) return variant;
+  }
+  return config.variants[config.variants.length - 1] ?? null;
+}
+function assignExperiment(config, subjectId, options = {}) {
+  const variant = chooseExperimentVariant(config, subjectId);
+  if (!variant) return null;
+  return {
+    experimentKey: config.experimentKey,
+    variant: variant.key,
+    indexUid: variant.indexUid,
+    sessionId: options.sessionId ?? subjectId,
+    config
+  };
+}
+function experimentSearchMetadata(assignment) {
+  if (!assignment) return void 0;
+  return {
+    experimentKey: assignment.experimentKey,
+    variant: assignment.variant,
+    ...assignment.sessionId ? { sessionId: assignment.sessionId } : {}
+  };
+}
+
 // src/client.ts
 var HeadbandError = class extends Error {
   constructor(message, status, code) {
@@ -11,22 +75,20 @@ var HeadbandError = class extends Error {
 };
 function headband(host, apiKey) {
   const baseUrl = host.replace(/\/+$/, "");
-  async function request(path, body) {
+  async function request(path, options = {}) {
+    const method = options.method ?? "POST";
     let response;
     try {
       response = await fetch(`${baseUrl}${path}`, {
-        method: "POST",
+        method,
         headers: {
-          "Content-Type": "application/json",
+          ...method === "POST" ? { "Content-Type": "application/json" } : {},
           Authorization: `Bearer ${apiKey}`
         },
-        body: JSON.stringify(body)
+        ...method === "POST" ? { body: JSON.stringify(options.body ?? {}) } : {}
       });
     } catch (err) {
-      throw new HeadbandError(
-        err instanceof Error ? err.message : "Network request failed",
-        0
-      );
+      throw new HeadbandError(err instanceof Error ? err.message : "Network request failed", 0);
     }
     if (!response.ok) {
       let errorBody = {};
@@ -45,25 +107,110 @@ function headband(host, apiKey) {
   return {
     search(index, query, params) {
       return request("/v1/search", {
-        index,
-        q: query,
-        ...params
+        body: {
+          index,
+          q: query,
+          ...params
+        }
       });
     },
     multiSearch(queries) {
-      return request("/v1/multi-search", { queries });
+      return request("/v1/multi-search", { body: { queries } });
+    },
+    async getExperimentConfigs(query) {
+      const response = await request(
+        buildExperimentConfigPath(query),
+        { method: "GET" }
+      );
+      return { experiments: response.data?.experiments ?? [] };
+    },
+    async assignExperiment(query) {
+      const response = await request(
+        "/v1/experiments/assign",
+        { body: query }
+      );
+      if (!response.data) {
+        throw new HeadbandError("Experiment assignment response missing data", 500);
+      }
+      return response.data;
+    },
+    async recordExperimentEvent(event) {
+      const response = await request("/v1/experiments/events", {
+        body: event
+      });
+      if (!response.data) {
+        throw new HeadbandError("Experiment event response missing data", 500);
+      }
+      return response.data;
+    },
+    warm(target, opts) {
+      return request("/v1/warm", {
+        body: { ...target, ...opts?.level ? { level: opts.level } : {} }
+      });
     }
   };
 }
 
+// src/filters.ts
+function quoteFilterValue(value) {
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  return JSON.stringify(value);
+}
+function filterEq(attribute, value) {
+  return `${attribute} = ${quoteFilterValue(value)}`;
+}
+function filterNotEq(attribute, value) {
+  return `${attribute} != ${quoteFilterValue(value)}`;
+}
+function filterIn(attribute, values) {
+  return `${attribute} IN [${values.map(quoteFilterValue).join(", ")}]`;
+}
+function filterExists(attribute) {
+  return `${attribute} EXISTS`;
+}
+function filterRange(attribute, range) {
+  const parts = [];
+  const gte = range.gte ?? range.min;
+  const lte = range.lte ?? range.max;
+  if (range.gt !== void 0) parts.push(`${attribute} > ${range.gt}`);
+  if (gte !== void 0) parts.push(`${attribute} >= ${gte}`);
+  if (range.lt !== void 0) parts.push(`${attribute} < ${range.lt}`);
+  if (lte !== void 0) parts.push(`${attribute} <= ${lte}`);
+  return parts.length ? andFilters(...parts) : void 0;
+}
+function normalizeFilter(input) {
+  if (!input) return [];
+  return (Array.isArray(input) ? input : [input]).filter((part) => Boolean(part));
+}
+function andFilters(...filters) {
+  const parts = filters.flatMap(normalizeFilter);
+  if (parts.length === 0) return void 0;
+  if (parts.length === 1) return parts[0];
+  return parts.map((part) => `(${part})`).join(" AND ");
+}
+function orFilters(...filters) {
+  const parts = filters.flatMap(normalizeFilter);
+  if (parts.length === 0) return void 0;
+  if (parts.length === 1) return parts[0];
+  return parts.map((part) => `(${part})`).join(" OR ");
+}
+function combineFilters(baseFilter, generatedFilter) {
+  const base = normalizeFilter(baseFilter);
+  const generated = normalizeFilter(generatedFilter);
+  const combined = [...base, ...generated];
+  if (combined.length === 0) return void 0;
+  if (combined.length === 1) return combined[0];
+  return combined;
+}
+
 // src/provider.tsx
 import {
   createContext,
   useContext,
   useCallback,
   useEffect,
-  useRef,
   useMemo,
+  useRef,
   useState
 } from "react";
 import { jsx } from "react/jsx-runtime";
@@ -71,9 +218,7 @@ var HeadbandContext = createContext(null);
 function useHeadbandContext() {
   const ctx = useContext(HeadbandContext);
   if (!ctx) {
-    throw new Error(
-      "useHeadbandContext must be used within a <HeadbandProvider>."
-    );
+    throw new Error("useHeadbandContext must be used within a <HeadbandProvider>.");
   }
   return ctx;
 }
@@ -83,18 +228,19 @@ function buildFilterString(refinements, ranges) {
     if (values.size === 0) return;
     if (values.size === 1) {
       const [v] = values;
-      parts.push(`${attribute} = "${v}"`);
+      parts.push(filterEq(attribute, v));
     } else {
-      const list = Array.from(values).map((v) => `"${v}"`).join(", ");
-      parts.push(`${attribute} IN [${list}]`);
+      parts.push(filterIn(attribute, Array.from(values)));
     }
   });
   ranges.forEach((range, attribute) => {
     if (range.min !== void 0) {
-      parts.push(`${attribute} >= ${range.min}`);
+      const generated = filterRange(attribute, { min: range.min });
+      if (generated) parts.push(generated);
     }
     if (range.max !== void 0) {
-      parts.push(`${attribute} <= ${range.max}`);
+      const generated = filterRange(attribute, { max: range.max });
+      if (generated) parts.push(generated);
     }
   });
   return parts.length > 0 ? parts.join(" AND ") : void 0;
@@ -103,96 +249,92 @@ function HeadbandProvider({
   client,
   index,
   initialQuery = "",
+  experiment = null,
+  baseFilter,
+  mode,
   children
 }) {
   const [query, setQueryRaw] = useState(initialQuery);
   const [results, setResults] = useState(null);
   const [isLoading, setIsLoading] = useState(false);
   const [error, setError] = useState(null);
-  const [refinements, setRefinements] = useState(
-    () => /* @__PURE__ */ new Map()
-  );
+  const [refinements, setRefinements] = useState(() => /* @__PURE__ */ new Map());
   const [ranges, setRanges] = useState(() => /* @__PURE__ */ new Map());
   const [sortBy, setSortBy] = useState(null);
   const [page, setPage] = useState(0);
   const [hitsPerPage, setHitsPerPage] = useState(20);
   const [facets, setFacets] = useState(() => /* @__PURE__ */ new Set());
-  const timerRef = useRef(null);
   const requestIdRef = useRef(0);
-  const refinementsRef = useRef(refinements);
-  refinementsRef.current = refinements;
-  const rangesRef = useRef(ranges);
-  rangesRef.current = ranges;
-  const facetsRef = useRef(facets);
-  facetsRef.current = facets;
+  const generatedFilter = useMemo(
+    () => buildFilterString(refinements, ranges),
+    [refinements, ranges]
+  );
+  const filter = useMemo(
+    () => combineFilters(baseFilter, generatedFilter),
+    [baseFilter, generatedFilter]
+  );
+  const facetList = useMemo(() => facets.size > 0 ? Array.from(facets) : void 0, [facets]);
+  const sortList = useMemo(() => sortBy ? [sortBy] : void 0, [sortBy]);
   const executeSearch = useCallback(() => {
-    const id = ++requestIdRef.current;
+    const requestId = ++requestIdRef.current;
     setIsLoading(true);
     setError(null);
-    const filter = buildFilterString(refinementsRef.current, rangesRef.current);
-    const facetList = facetsRef.current.size > 0 ? Array.from(facetsRef.current) : void 0;
-    const sortList = sortBy ? [sortBy] : void 0;
     const params = {
       limit: hitsPerPage,
       offset: page * hitsPerPage,
       ...filter ? { filter } : {},
       ...facetList ? { facets: facetList } : {},
       ...sortList ? { sort: sortList } : {},
+      ...experiment ? experiment : {},
+      ...mode ? { mode } : {},
       attributesToHighlight: ["*"]
     };
     client.search(index, query, params).then((res) => {
-      if (id === requestIdRef.current) {
-        setResults(res);
-        setIsLoading(false);
+      if (requestId !== requestIdRef.current) {
+        return;
       }
+      setResults(res);
+      setIsLoading(false);
     }).catch((err) => {
-      if (id === requestIdRef.current) {
-        setError(err instanceof Error ? err : new Error(String(err)));
-        setIsLoading(false);
+      if (requestId !== requestIdRef.current) {
+        return;
       }
+      setError(err instanceof Error ? err : new Error(String(err)));
+      setIsLoading(false);
     });
-  }, [client, index, query, sortBy, page, hitsPerPage]);
+  }, [client, index, query, filter, facetList, sortList, experiment, mode, page, hitsPerPage]);
   useEffect(() => {
-    if (timerRef.current) {
-      clearTimeout(timerRef.current);
-    }
-    timerRef.current = setTimeout(executeSearch, 200);
+    const timer = setTimeout(executeSearch, 200);
     return () => {
-      if (timerRef.current) clearTimeout(timerRef.current);
+      clearTimeout(timer);
     };
-  }, [executeSearch, refinements, ranges, facets]);
+  }, [executeSearch]);
   const setQuery = useCallback((q) => {
     setQueryRaw(q);
     setPage(0);
   }, []);
-  const toggleRefinement = useCallback(
-    (attribute, value2) => {
-      setRefinements((prev) => {
-        const next = new Map(prev);
-        const current = new Set(next.get(attribute) ?? []);
-        if (current.has(value2)) {
-          current.delete(value2);
-        } else {
-          current.add(value2);
-        }
-        next.set(attribute, current);
-        return next;
-      });
-      setPage(0);
-    },
-    []
-  );
-  const setRange = useCallback(
-    (attribute, range) => {
-      setRanges((prev) => {
-        const next = new Map(prev);
-        next.set(attribute, range);
-        return next;
-      });
-      setPage(0);
-    },
-    []
-  );
+  const toggleRefinement = useCallback((attribute, value2) => {
+    setRefinements((prev) => {
+      const next = new Map(prev);
+      const current = new Set(next.get(attribute) ?? []);
+      if (current.has(value2)) {
+        current.delete(value2);
+      } else {
+        current.add(value2);
+      }
+      next.set(attribute, current);
+      return next;
+    });
+    setPage(0);
+  }, []);
+  const setRange = useCallback((attribute, range) => {
+    setRanges((prev) => {
+      const next = new Map(prev);
+      next.set(attribute, range);
+      return next;
+    });
+    setPage(0);
+  }, []);
   const clearRange = useCallback((attribute) => {
     setRanges((prev) => {
       const next = new Map(prev);
@@ -248,7 +390,18 @@ function HeadbandProvider({
       unregisterFacet,
       refresh
     }),
-    [setQuery, toggleRefinement, setRange, clearRange, registerFacet, unregisterFacet, refresh]
+    [
+      setQuery,
+      setPage,
+      setSortBy,
+      setHitsPerPage,
+      toggleRefinement,
+      setRange,
+      clearRange,
+      registerFacet,
+      unregisterFacet,
+      refresh
+    ]
   );
   const value = useMemo(
     () => ({ client, index, state, actions }),
@@ -310,18 +463,19 @@ function useRefinementList({
       actions.unregisterFacet(attribute);
     };
   }, [attribute, actions]);
-  const refined = state.refinements.get(attribute) ?? /* @__PURE__ */ new Set();
+  const refined = state.refinements.get(attribute);
   const items = useMemo3(() => {
+    const activeRefinements = refined ?? /* @__PURE__ */ new Set();
     const distribution = state.results?.facetDistribution?.[attribute] ?? {};
     const allValues = /* @__PURE__ */ new Set([
       ...Object.keys(distribution),
-      ...refined
+      ...activeRefinements
     ]);
     let result = Array.from(allValues).map(
       (value) => ({
         value,
         count: distribution[value] ?? 0,
-        isRefined: refined.has(value)
+        isRefined: activeRefinements.has(value)
       })
     );
     if (sortOrder === "alpha") {
@@ -624,7 +778,11 @@ function SearchBox({
 // src/components/Hits.tsx
 import { Fragment, jsx as jsx3, jsxs as jsxs2 } from "react/jsx-runtime";
 function DefaultHit({ hit }) {
-  const { _formatted, __data, ...rest } = hit;
+  const rest = Object.fromEntries(
+    Object.entries(hit).filter(
+      ([key]) => key !== "_formatted" && key !== "__data"
+    )
+  );
   return /* @__PURE__ */ jsx3("div", { className: "rounded-lg border border-gray-200 bg-white p-4 text-sm dark:border-gray-700 dark:bg-gray-900", children: /* @__PURE__ */ jsx3("pre", { className: "overflow-x-auto whitespace-pre-wrap text-xs text-gray-700 dark:text-gray-300", children: JSON.stringify(rest, null, 2) }) });
 }
 function DefaultEmpty() {
@@ -685,7 +843,7 @@ function RefinementList({
     sortBy
   });
   const handleChange = useCallback8(
-    (value) => (_e) => {
+    (value) => () => {
       refine(value);
     },
     [refine]
@@ -914,11 +1072,7 @@ function Highlight({
 }
 
 // src/components/RangeInput.tsx
-import {
-  useState as useState2,
-  useCallback as useCallback11,
-  useEffect as useEffect3
-} from "react";
+import { useCallback as useCallback11 } from "react";
 import { jsx as jsx9, jsxs as jsxs6 } from "react/jsx-runtime";
 function RangeInput({
   attribute,
@@ -929,17 +1083,15 @@ function RangeInput({
   maxPlaceholder = "Max"
 }) {
   const { min, max, stats, setRange, clear } = useRange({ attribute });
-  const [localMin, setLocalMin] = useState2(min !== void 0 ? String(min) : "");
-  const [localMax, setLocalMax] = useState2(max !== void 0 ? String(max) : "");
-  useEffect3(() => {
-    setLocalMin(min !== void 0 ? String(min) : "");
-  }, [min]);
-  useEffect3(() => {
-    setLocalMax(max !== void 0 ? String(max) : "");
-  }, [max]);
+  const defaultMin = min !== void 0 ? String(min) : "";
+  const defaultMax = max !== void 0 ? String(max) : "";
+  const formKey = `${attribute}:${defaultMin}:${defaultMax}`;
   const handleSubmit = useCallback11(
     (e) => {
       e.preventDefault();
+      const formData = new FormData(e.currentTarget);
+      const localMin = String(formData.get("min") ?? "");
+      const localMax = String(formData.get("max") ?? "");
       const parsedMin = localMin !== "" ? Number(localMin) : void 0;
       const parsedMax = localMax !== "" ? Number(localMax) : void 0;
       if (parsedMin === void 0 && parsedMax === void 0) {
@@ -951,15 +1103,7 @@ function RangeInput({
         });
       }
     },
-    [localMin, localMax, setRange, clear]
-  );
-  const handleMinChange = useCallback11(
-    (e) => setLocalMin(e.target.value),
-    []
-  );
-  const handleMaxChange = useCallback11(
-    (e) => setLocalMax(e.target.value),
-    []
+    [setRange, clear]
   );
   const containerClass = styled ? `space-y-2 ${className ?? ""}`.trim() : className ?? "";
   const inputClass = styled ? "w-full rounded border border-gray-200 bg-white px-2.5 py-1.5 text-sm outline-none transition-colors placeholder:text-gray-400 focus:border-indigo-500 focus:ring-2 focus:ring-indigo-500/20 dark:border-gray-700 dark:bg-gray-900 dark:text-white dark:placeholder:text-gray-500" : "";
@@ -994,9 +1138,9 @@ function RangeInput({
           /* @__PURE__ */ jsx9(
             "input",
             {
+              name: "min",
               type: "number",
-              value: localMin,
-              onChange: handleMinChange,
+              defaultValue: defaultMin,
               placeholder: minPlaceholder,
               "aria-label": `Minimum ${attribute}`,
               className: inputClass
@@ -1013,9 +1157,9 @@ function RangeInput({
           /* @__PURE__ */ jsx9(
             "input",
             {
+              name: "max",
               type: "number",
-              value: localMax,
-              onChange: handleMaxChange,
+              defaultValue: defaultMax,
               placeholder: maxPlaceholder,
               "aria-label": `Maximum ${attribute}`,
               className: inputClass
@@ -1024,7 +1168,8 @@ function RangeInput({
           /* @__PURE__ */ jsx9("button", { type: "submit", className: buttonClass, children: "Go" })
         ] })
       ]
-    }
+    },
+    formKey
   );
 }
 
@@ -1084,7 +1229,21 @@ export {
   SearchBox,
   SortBy,
   Stats,
+  andFilters,
+  assignExperiment,
+  buildExperimentConfigPath,
+  chooseExperimentVariant,
+  combineFilters,
+  experimentSearchMetadata,
+  filterEq,
+  filterExists,
+  filterIn,
+  filterNotEq,
+  filterRange,
   headband,
+  isRunnableExperiment,
+  orFilters,
+  quoteFilterValue,
   useHeadbandContext,
   useHighlight,
   useHits,

package/package.json

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