@headband/react 0.1.1 → 0.2.0

package/dist/index.js

@@ -32,7 +32,21 @@ __export(index_exports, {
   SearchBox: () => SearchBox,
   SortBy: () => SortBy,
   Stats: () => Stats,
+  andFilters: () => andFilters,
+  assignExperiment: () => assignExperiment,
+  buildExperimentConfigPath: () => buildExperimentConfigPath,
+  chooseExperimentVariant: () => chooseExperimentVariant,
+  combineFilters: () => combineFilters,
+  experimentSearchMetadata: () => experimentSearchMetadata,
+  filterEq: () => filterEq,
+  filterExists: () => filterExists,
+  filterIn: () => filterIn,
+  filterNotEq: () => filterNotEq,
+  filterRange: () => filterRange,
   headband: () => headband,
+  isRunnableExperiment: () => isRunnableExperiment,
+  orFilters: () => orFilters,
+  quoteFilterValue: () => quoteFilterValue,
   useHeadbandContext: () => useHeadbandContext,
   useHighlight: () => useHighlight,
   useHits: () => useHits,
@@ -46,6 +60,70 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// 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) {
@@ -57,22 +135,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 = {};
@@ -91,17 +167,102 @@ 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
 var import_react = require("react");
 var import_jsx_runtime = require("react/jsx-runtime");
@@ -109,9 +270,7 @@ var HeadbandContext = (0, import_react.createContext)(null);
 function useHeadbandContext() {
   const ctx = (0, import_react.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;
 }
@@ -121,18 +280,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;
@@ -141,96 +301,92 @@ function HeadbandProvider({
   client,
   index,
   initialQuery = "",
+  experiment = null,
+  baseFilter,
+  mode,
   children
 }) {
   const [query, setQueryRaw] = (0, import_react.useState)(initialQuery);
   const [results, setResults] = (0, import_react.useState)(null);
   const [isLoading, setIsLoading] = (0, import_react.useState)(false);
   const [error, setError] = (0, import_react.useState)(null);
-  const [refinements, setRefinements] = (0, import_react.useState)(
-    () => /* @__PURE__ */ new Map()
-  );
+  const [refinements, setRefinements] = (0, import_react.useState)(() => /* @__PURE__ */ new Map());
   const [ranges, setRanges] = (0, import_react.useState)(() => /* @__PURE__ */ new Map());
   const [sortBy, setSortBy] = (0, import_react.useState)(null);
   const [page, setPage] = (0, import_react.useState)(0);
   const [hitsPerPage, setHitsPerPage] = (0, import_react.useState)(20);
   const [facets, setFacets] = (0, import_react.useState)(() => /* @__PURE__ */ new Set());
-  const timerRef = (0, import_react.useRef)(null);
   const requestIdRef = (0, import_react.useRef)(0);
-  const refinementsRef = (0, import_react.useRef)(refinements);
-  refinementsRef.current = refinements;
-  const rangesRef = (0, import_react.useRef)(ranges);
-  rangesRef.current = ranges;
-  const facetsRef = (0, import_react.useRef)(facets);
-  facetsRef.current = facets;
+  const generatedFilter = (0, import_react.useMemo)(
+    () => buildFilterString(refinements, ranges),
+    [refinements, ranges]
+  );
+  const filter = (0, import_react.useMemo)(
+    () => combineFilters(baseFilter, generatedFilter),
+    [baseFilter, generatedFilter]
+  );
+  const facetList = (0, import_react.useMemo)(() => facets.size > 0 ? Array.from(facets) : void 0, [facets]);
+  const sortList = (0, import_react.useMemo)(() => sortBy ? [sortBy] : void 0, [sortBy]);
   const executeSearch = (0, import_react.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]);
   (0, import_react.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 = (0, import_react.useCallback)((q) => {
     setQueryRaw(q);
     setPage(0);
   }, []);
-  const toggleRefinement = (0, import_react.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 = (0, import_react.useCallback)(
-    (attribute, range) => {
-      setRanges((prev) => {
-        const next = new Map(prev);
-        next.set(attribute, range);
-        return next;
-      });
-      setPage(0);
-    },
-    []
-  );
+  const toggleRefinement = (0, import_react.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 = (0, import_react.useCallback)((attribute, range) => {
+    setRanges((prev) => {
+      const next = new Map(prev);
+      next.set(attribute, range);
+      return next;
+    });
+    setPage(0);
+  }, []);
   const clearRange = (0, import_react.useCallback)((attribute) => {
     setRanges((prev) => {
       const next = new Map(prev);
@@ -286,7 +442,18 @@ function HeadbandProvider({
       unregisterFacet,
       refresh
     }),
-    [setQuery, toggleRefinement, setRange, clearRange, registerFacet, unregisterFacet, refresh]
+    [
+      setQuery,
+      setPage,
+      setSortBy,
+      setHitsPerPage,
+      toggleRefinement,
+      setRange,
+      clearRange,
+      registerFacet,
+      unregisterFacet,
+      refresh
+    ]
   );
   const value = (0, import_react.useMemo)(
     () => ({ client, index, state, actions }),
@@ -348,18 +515,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 = (0, import_react4.useMemo)(() => {
+    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") {
@@ -659,7 +827,11 @@ function SearchBox({
 // src/components/Hits.tsx
 var import_jsx_runtime3 = require("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__ */ (0, import_jsx_runtime3.jsx)("div", { className: "rounded-lg border border-gray-200 bg-white p-4 text-sm dark:border-gray-700 dark:bg-gray-900", children: /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("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() {
@@ -720,7 +892,7 @@ function RefinementList({
     sortBy
   });
   const handleChange = (0, import_react11.useCallback)(
-    (value) => (_e) => {
+    (value) => () => {
       refine(value);
     },
     [refine]
@@ -960,17 +1132,15 @@ function RangeInput({
   maxPlaceholder = "Max"
 }) {
   const { min, max, stats, setRange, clear } = useRange({ attribute });
-  const [localMin, setLocalMin] = (0, import_react14.useState)(min !== void 0 ? String(min) : "");
-  const [localMax, setLocalMax] = (0, import_react14.useState)(max !== void 0 ? String(max) : "");
-  (0, import_react14.useEffect)(() => {
-    setLocalMin(min !== void 0 ? String(min) : "");
-  }, [min]);
-  (0, import_react14.useEffect)(() => {
-    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 = (0, import_react14.useCallback)(
     (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) {
@@ -982,15 +1152,7 @@ function RangeInput({
         });
       }
     },
-    [localMin, localMax, setRange, clear]
-  );
-  const handleMinChange = (0, import_react14.useCallback)(
-    (e) => setLocalMin(e.target.value),
-    []
-  );
-  const handleMaxChange = (0, import_react14.useCallback)(
-    (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" : "";
@@ -1025,9 +1187,9 @@ function RangeInput({
           /* @__PURE__ */ (0, import_jsx_runtime9.jsx)(
             "input",
             {
+              name: "min",
               type: "number",
-              value: localMin,
-              onChange: handleMinChange,
+              defaultValue: defaultMin,
               placeholder: minPlaceholder,
               "aria-label": `Minimum ${attribute}`,
               className: inputClass
@@ -1044,9 +1206,9 @@ function RangeInput({
           /* @__PURE__ */ (0, import_jsx_runtime9.jsx)(
             "input",
             {
+              name: "max",
               type: "number",
-              value: localMax,
-              onChange: handleMaxChange,
+              defaultValue: defaultMax,
               placeholder: maxPlaceholder,
               "aria-label": `Maximum ${attribute}`,
               className: inputClass
@@ -1055,7 +1217,8 @@ function RangeInput({
           /* @__PURE__ */ (0, import_jsx_runtime9.jsx)("button", { type: "submit", className: buttonClass, children: "Go" })
         ] })
       ]
-    }
+    },
+    formKey
   );
 }
 
@@ -1116,7 +1279,21 @@ function PoweredBy({
   SearchBox,
   SortBy,
   Stats,
+  andFilters,
+  assignExperiment,
+  buildExperimentConfigPath,
+  chooseExperimentVariant,
+  combineFilters,
+  experimentSearchMetadata,
+  filterEq,
+  filterExists,
+  filterIn,
+  filterNotEq,
+  filterRange,
   headband,
+  isRunnableExperiment,
+  orFilters,
+  quoteFilterValue,
   useHeadbandContext,
   useHighlight,
   useHits,