@headband/react 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,416 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode, ComponentType } from 'react';
+
+/**
+ * Headband search client.
+ *
+ * Makes requests to the Headband `/v1/search` and `/v1/multi-search` endpoints.
+ */
+interface SearchParams {
+    filter?: string;
+    facets?: string[];
+    sort?: string[];
+    limit?: number;
+    offset?: number;
+    attributesToHighlight?: string[];
+    attributesToRetrieve?: string[];
+    attributesToCrop?: string[];
+    cropLength?: number;
+    showMatchesPosition?: boolean;
+    matchingStrategy?: "all" | "last" | "frequency";
+}
+interface SearchResponse {
+    hits: Record<string, unknown>[];
+    estimatedTotalHits?: number;
+    totalHits?: number;
+    processingTimeMs: number;
+    query: string;
+    facetDistribution?: Record<string, Record<string, number>>;
+    facetStats?: Record<string, {
+        min: number;
+        max: number;
+    }>;
+}
+interface MultiSearchQuery {
+    indexUid: string;
+    q: string;
+    filter?: string;
+    facets?: string[];
+    sort?: string[];
+    limit?: number;
+    offset?: number;
+    attributesToHighlight?: string[];
+    attributesToRetrieve?: string[];
+}
+interface MultiSearchResponse {
+    results: Array<SearchResponse & {
+        indexUid: string;
+    }>;
+}
+interface HeadbandClient {
+    search(index: string, query: string, params?: SearchParams): Promise<SearchResponse>;
+    multiSearch(queries: MultiSearchQuery[]): Promise<MultiSearchResponse>;
+}
+declare class HeadbandError extends Error {
+    readonly status: number;
+    readonly code: string | undefined;
+    constructor(message: string, status: number, code?: string);
+}
+declare function headband(host: string, apiKey: string): HeadbandClient;
+
+/** Map of attribute -> selected values for facet refinements. */
+type RefinementMap = Map<string, Set<string>>;
+/** Numeric range filter: attribute -> { min?, max? }. */
+type RangeMap = Map<string, {
+    min?: number;
+    max?: number;
+}>;
+interface SearchState {
+    query: string;
+    results: SearchResponse | null;
+    isLoading: boolean;
+    error: Error | null;
+    refinements: RefinementMap;
+    ranges: RangeMap;
+    sortBy: string | null;
+    page: number;
+    hitsPerPage: number;
+    facets: Set<string>;
+}
+interface SearchActions {
+    setQuery: (query: string) => void;
+    setPage: (page: number) => void;
+    setSortBy: (sort: string | null) => void;
+    setHitsPerPage: (n: number) => void;
+    toggleRefinement: (attribute: string, value: string) => void;
+    setRange: (attribute: string, range: {
+        min?: number;
+        max?: number;
+    }) => void;
+    clearRange: (attribute: string) => void;
+    registerFacet: (attribute: string) => void;
+    unregisterFacet: (attribute: string) => void;
+    refresh: () => void;
+}
+interface HeadbandContextValue {
+    client: HeadbandClient;
+    index: string;
+    state: SearchState;
+    actions: SearchActions;
+}
+declare function useHeadbandContext(): HeadbandContextValue;
+interface HeadbandProviderProps {
+    client: HeadbandClient;
+    index: string;
+    initialQuery?: string;
+    children: ReactNode;
+}
+declare function HeadbandProvider({ client, index, initialQuery, children, }: HeadbandProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Core hook that exposes the full search state and actions.
+ *
+ * Most consumers should prefer the specialised hooks (useSearchBox, useHits,
+ * etc.) — this hook is useful when you need direct access to everything.
+ */
+declare function useSearch(): SearchState & SearchActions;
+
+interface UseSearchBoxReturn {
+    /** Current query string. */
+    query: string;
+    /** Update the query — resets pagination and triggers a debounced search. */
+    setQuery: (query: string) => void;
+    /** Clear the query to an empty string. */
+    clear: () => void;
+}
+/**
+ * Binds to the search input. Returns the current query plus setters.
+ */
+declare function useSearchBox(): UseSearchBoxReturn;
+
+interface Hit<T = Record<string, unknown>> {
+    /** The original document fields. */
+    [key: string]: unknown;
+    /** Highlighted / formatted version of fields (from attributesToHighlight). */
+    _formatted?: Record<string, unknown>;
+    /** Typed access helper — same as spreading the hit. */
+    __data: T;
+}
+interface UseHitsReturn<T = Record<string, unknown>> {
+    hits: Hit<T>[];
+    isLoading: boolean;
+    error: Error | null;
+}
+/**
+ * Returns the current search hits with loading / error state.
+ */
+declare function useHits<T extends Record<string, unknown> = Record<string, unknown>>(): UseHitsReturn<T>;
+
+interface RefinementListItem {
+    value: string;
+    count: number;
+    isRefined: boolean;
+}
+interface UseRefinementListProps {
+    /** The facet attribute to refine on (e.g. "genres"). */
+    attribute: string;
+    /** Maximum number of facet values to display. Default: 20. */
+    limit?: number;
+    /** Sort facet values: "count" (desc) or "alpha" (asc). Default: "count". */
+    sortBy?: "count" | "alpha";
+}
+interface UseRefinementListReturn {
+    items: RefinementListItem[];
+    /** Toggle a facet value on/off. */
+    refine: (value: string) => void;
+    /** Whether there are facet values available to toggle. */
+    canToggle: boolean;
+    isLoading: boolean;
+}
+/**
+ * Provides facet filtering for a given attribute.
+ *
+ * Registers the attribute as a requested facet so the provider includes it in
+ * search requests automatically.
+ */
+declare function useRefinementList({ attribute, limit, sortBy: sortOrder, }: UseRefinementListProps): UseRefinementListReturn;
+
+interface UsePaginationReturn {
+    currentPage: number;
+    totalPages: number;
+    totalHits: number;
+    setPage: (page: number) => void;
+    canPrevious: boolean;
+    canNext: boolean;
+    /** Array of page numbers useful for rendering a page list. */
+    pages: number[];
+}
+/**
+ * Pagination state derived from the current search results.
+ *
+ * Pages are 0-indexed internally but the `pages` array is 0-indexed as well
+ * for simplicity. The consumer can add 1 for display purposes.
+ */
+declare function usePagination(): UsePaginationReturn;
+
+interface UseStatsReturn {
+    totalHits: number;
+    processingTimeMs: number;
+    query: string;
+    isLoading: boolean;
+}
+/**
+ * Returns summary stats about the current search results.
+ */
+declare function useStats(): UseStatsReturn;
+
+interface SortByItem {
+    /** The sort value sent to the API (e.g. "rating:desc"). */
+    value: string;
+    /** Human-readable label (e.g. "Rating (high to low)"). */
+    label: string;
+}
+interface UseSortByProps {
+    items: SortByItem[];
+}
+interface UseSortByReturn {
+    /** Currently active sort value, or null for relevance. */
+    currentSort: string | null;
+    /** Set the active sort. Pass null to reset to default relevance. */
+    setSort: (value: string | null) => void;
+    /** The items list with an `isSelected` flag added. */
+    items: Array<SortByItem & {
+        isSelected: boolean;
+    }>;
+}
+/**
+ * Sort-by dropdown state.
+ */
+declare function useSortBy({ items }: UseSortByProps): UseSortByReturn;
+
+interface UseRangeProps {
+    /** The numeric attribute to filter on (e.g. "price"). */
+    attribute: string;
+}
+interface UseRangeReturn {
+    /** Current min bound, or undefined if not set. */
+    min: number | undefined;
+    /** Current max bound, or undefined if not set. */
+    max: number | undefined;
+    /** Facet stats from the engine (overall min/max for this attribute). */
+    stats: {
+        min: number;
+        max: number;
+    } | undefined;
+    /** Set the range filter. Omit min/max to leave that side unbounded. */
+    setRange: (range: {
+        min?: number;
+        max?: number;
+    }) => void;
+    /** Remove the range filter entirely. */
+    clear: () => void;
+    isLoading: boolean;
+}
+/**
+ * Numeric range filter for a given attribute.
+ */
+declare function useRange({ attribute }: UseRangeProps): UseRangeReturn;
+
+interface UseHighlightProps {
+    /** The hit object from useHits. */
+    hit: Record<string, unknown>;
+    /** The attribute to highlight (e.g. "title"). */
+    attribute: string;
+}
+interface UseHighlightReturn {
+    /** The highlighted string with <em> tags, or the raw value if no highlight. */
+    value: string;
+    /** Whether the value actually contains highlight marks. */
+    highlighted: boolean;
+}
+/**
+ * Extracts the highlighted value for a specific attribute from a hit.
+ */
+declare function useHighlight({ hit, attribute, }: UseHighlightProps): UseHighlightReturn;
+
+interface SearchBoxProps {
+    /** Placeholder text. */
+    placeholder?: string;
+    /** Additional CSS class names. */
+    className?: string;
+    /** Auto-focus the input on mount. */
+    autoFocus?: boolean;
+    /** Called on every query change (after internal state updates). */
+    onQueryChange?: (query: string) => void;
+    /** Whether to render the default Tailwind styles. Set false for unstyled. */
+    styled?: boolean;
+}
+/**
+ * Search input component with built-in clear button.
+ */
+declare function SearchBox({ placeholder, className, autoFocus, onQueryChange, styled, }: SearchBoxProps): react_jsx_runtime.JSX.Element;
+
+interface HitsProps<T extends Record<string, unknown> = Record<string, unknown>> {
+    /** Custom component to render each hit. Receives the hit as a prop. */
+    hitComponent?: ComponentType<{
+        hit: Hit<T>;
+    }>;
+    /** Additional CSS class names for the list container. */
+    className?: string;
+    /** Content to show when there are no results. */
+    emptyComponent?: ReactNode;
+    /** Whether to render the default Tailwind styles. Set false for unstyled. */
+    styled?: boolean;
+}
+/**
+ * Renders search result hits.
+ */
+declare function Hits<T extends Record<string, unknown> = Record<string, unknown>>({ hitComponent, className, emptyComponent, styled, }: HitsProps<T>): react_jsx_runtime.JSX.Element;
+
+interface RefinementListProps extends UseRefinementListProps {
+    /** Additional CSS class names. */
+    className?: string;
+    /** Whether to render the default Tailwind styles. Set false for unstyled. */
+    styled?: boolean;
+    /** Optional heading displayed above the list. */
+    header?: string;
+}
+/**
+ * Checkbox list of facet values with counts.
+ */
+declare function RefinementList({ attribute, limit, sortBy, className, styled, header, }: RefinementListProps): react_jsx_runtime.JSX.Element;
+
+interface PaginationProps {
+    /** Additional CSS class names. */
+    className?: string;
+    /** Whether to render the default Tailwind styles. Set false for unstyled. */
+    styled?: boolean;
+}
+/**
+ * Page navigation with Previous / Next and numbered page buttons.
+ */
+declare function Pagination({ className, styled }: PaginationProps): react_jsx_runtime.JSX.Element | null;
+
+interface StatsProps {
+    /** Additional CSS class names. */
+    className?: string;
+    /** Whether to render the default Tailwind styles. Set false for unstyled. */
+    styled?: boolean;
+    /** Custom render function. */
+    render?: (stats: {
+        totalHits: number;
+        processingTimeMs: number;
+        query: string;
+    }) => string;
+}
+/**
+ * Displays "X results in Yms".
+ */
+declare function Stats({ className, styled, render }: StatsProps): react_jsx_runtime.JSX.Element | null;
+
+interface SortByProps {
+    /** Sort options to display. */
+    items: SortByItem[];
+    /** Additional CSS class names. */
+    className?: string;
+    /** Whether to render the default Tailwind styles. Set false for unstyled. */
+    styled?: boolean;
+    /** Label for the sort select (for accessibility). */
+    label?: string;
+}
+/**
+ * Sort-by select dropdown.
+ */
+declare function SortBy({ items: itemsProp, className, styled, label, }: SortByProps): react_jsx_runtime.JSX.Element;
+
+interface HighlightProps {
+    /** The hit object from useHits. */
+    hit: Record<string, unknown>;
+    /** The attribute to highlight (e.g. "title"). */
+    attribute: string;
+    /** Additional CSS class names. */
+    className?: string;
+    /** Whether to render the default Tailwind styles. Set false for unstyled. */
+    styled?: boolean;
+    /** Tag name for the highlight wrapper. Defaults to "span". */
+    tagName?: keyof HTMLElementTagNameMap;
+}
+/**
+ * Renders highlighted text for a hit attribute.
+ *
+ * Strips all HTML except `<em>` tags so it is safe to use with
+ * dangerouslySetInnerHTML.
+ */
+declare function Highlight({ hit, attribute, className, styled, tagName: Tag, }: HighlightProps): react_jsx_runtime.JSX.Element;
+
+interface RangeInputProps extends UseRangeProps {
+    /** Additional CSS class names. */
+    className?: string;
+    /** Whether to render the default Tailwind styles. Set false for unstyled. */
+    styled?: boolean;
+    /** Optional heading above the inputs. */
+    header?: string;
+    /** Placeholder for the min input. */
+    minPlaceholder?: string;
+    /** Placeholder for the max input. */
+    maxPlaceholder?: string;
+}
+/**
+ * Min/max number inputs for numeric range filtering.
+ */
+declare function RangeInput({ attribute, className, styled, header, minPlaceholder, maxPlaceholder, }: RangeInputProps): react_jsx_runtime.JSX.Element;
+
+interface PoweredByProps {
+    /** Additional CSS class names. */
+    className?: string;
+    /** Whether to render the default Tailwind styles. Set false for unstyled. */
+    styled?: boolean;
+    /** Override the link URL. Defaults to "https://headband.dev". */
+    href?: string;
+}
+/**
+ * "Powered by Headband" badge with link.
+ */
+declare function PoweredBy({ className, styled, href, }: PoweredByProps): react_jsx_runtime.JSX.Element;
+
+export { type HeadbandClient, type HeadbandContextValue, HeadbandError, HeadbandProvider, type HeadbandProviderProps, Highlight, type HighlightProps, type Hit, Hits, type HitsProps, 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 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, headband, useHeadbandContext, useHighlight, useHits, usePagination, useRange, useRefinementList, useSearch, useSearchBox, useSortBy, useStats };