@uniformdev/search 0.0.4 → 0.0.6

package/dist/react.d.mts

@@ -1,6 +1,6 @@
 import * as react from 'react';
-import { FC, ReactNode } from 'react';
-import { d as Pagination, S as SearchHit, a as Facets, P as PageSize, F as FacetBy, h as SearchParams, C as CollectionResult, g as SearchItemConfig } from './client-DOew5kqb.mjs';
+import { FC, ReactNode, InputHTMLAttributes, HTMLAttributes } from 'react';
+import { d as Pagination, S as SearchHit, a as Facets, P as PageSize, h as SearchParams, C as CollectionResult, F as FacetBy, g as SearchItemConfig } from './client-DOew5kqb.mjs';
 
 interface SearchProviderProps {
     children: ReactNode;
@@ -39,6 +39,18 @@ interface UseSearchReturn {
      *  (App Router slots) instead of it being passed to the provider. */
     registerOrderBy: (id: string, orderBy: unknown) => void;
     unregisterOrderBy: (id: string) => void;
+    /** The search function the provider drives (typo-tolerance wrapper included). Exposed
+     *  so in-engine components (e.g. an autocomplete box) issue the SAME request shape. */
+    performSearch: (params: SearchParams) => Promise<CollectionResult>;
+    /** Fields the query string is matched against (as configured on the engine). */
+    queryBy?: string[];
+    /** Locale the search is scoped to (per-locale collection). */
+    locale?: string;
+    /** Always-applied base `filter_by` string (from the engine's base filters). */
+    baseFilterString?: string;
+    /** The active facet selections as a `performSearch` `filters` object — mirrors the
+     *  main results request so an autocomplete can reproduce the current filtered context. */
+    currentFilters: Record<string, unknown>;
     filterOptions: FacetBy[];
     setFilterOptions: (filters: FacetBy[]) => void;
     /** Additive registration of a single facet option (keyed by fieldKey). Used by facet
@@ -56,6 +68,103 @@ declare const SearchProvider: FC<SearchProviderProps>;
 
 declare function useSearch(): UseSearchReturn;
 
+interface UseAutocompleteOptions {
+    /**
+     * The search function (same signature used by `SearchProvider`). Typically
+     * `createSearchClient(...).performSearch`.
+     */
+    performSearch: (params: SearchParams) => Promise<CollectionResult>;
+    /** Fields to query against (mirrors `SearchProvider`'s `queryBy`). */
+    queryBy?: string[];
+    /** A base Typesense `filter_by` string applied to every request. */
+    baseFilterBy?: string;
+    /** Active facet selections (same `filters` object `SearchProvider` sends), so the
+     *  autocomplete request mirrors the main results' filtered context. */
+    filters?: Record<string, unknown>;
+    /** Locale to scope the search to (per-locale collection). */
+    locale?: string;
+    /** Max number of suggestions to fetch/show. Default: 6. */
+    perPage?: number;
+    /** Minimum number of characters before a request is made. Default: 1. */
+    minQueryLength?: number;
+    /** Debounce, in ms, between the last keystroke and the request. Default: 150. */
+    debounceMs?: number;
+    /** Open the panel as soon as the input is focused (if there is anything to show). Default: false. */
+    openOnFocus?: boolean;
+    /**
+     * Called when a suggestion is chosen (Enter on the active item, or a click). Use this to
+     * navigate to the item's page.
+     */
+    onSelect?: (item: SearchHit) => void;
+    /**
+     * Called when the raw query is submitted (Enter with no active suggestion). Use this to send
+     * the user to a full search-results page.
+     */
+    onSubmit?: (query: string) => void;
+    maxTypos?: number;
+    minLengthFor1Typo?: number;
+    minLengthFor2Typos?: number;
+    typoFallbackThreshold?: number;
+    prioritizeExactMatch?: boolean;
+}
+interface AutocompleteInputProps extends InputHTMLAttributes<HTMLInputElement> {
+    role: 'combobox';
+    'aria-autocomplete': 'list';
+    'aria-expanded': boolean;
+    'aria-controls': string;
+    'aria-activedescendant'?: string;
+    autoComplete: 'off';
+}
+interface AutocompleteListboxProps extends HTMLAttributes<HTMLElement> {
+    role: 'listbox';
+    id: string;
+}
+interface AutocompleteItemProps extends HTMLAttributes<HTMLElement> {
+    role: 'option';
+    id: string;
+    'aria-selected': boolean;
+}
+interface UseAutocompleteReturn {
+    /** Current input value. */
+    query: string;
+    /** Set the input value programmatically (does not trigger `onSubmit`). */
+    setQuery: (value: string) => void;
+    /** The current suggestions (top hits for the query). */
+    suggestions: SearchHit[];
+    /** True while a request is in flight. */
+    isLoading: boolean;
+    /** Whether the suggestions panel should be shown. */
+    isOpen: boolean;
+    /** Index of the keyboard-active suggestion, or -1 when none is active. */
+    activeIndex: number;
+    /** The keyboard-active suggestion, or null. */
+    activeItem: SearchHit | null;
+    /** Open the panel (if there is anything to show). */
+    open: () => void;
+    /** Close the panel and clear the active item. */
+    close: () => void;
+    /** Clear the query, suggestions, and close the panel. */
+    clear: () => void;
+    /** Select a suggestion (fires `onSelect` and closes the panel). */
+    selectItem: (item: SearchHit) => void;
+    /** Props for a `<label>` associated with the input. */
+    getLabelProps: () => {
+        id: string;
+        htmlFor: string;
+    };
+    /** Props for the `<input>` (combobox). Pass-through props are merged, yours win. */
+    getInputProps: (userProps?: InputHTMLAttributes<HTMLInputElement>) => AutocompleteInputProps;
+    /** Props for the suggestions container (listbox). */
+    getListboxProps: (userProps?: HTMLAttributes<HTMLElement>) => AutocompleteListboxProps;
+    /** Props for a single suggestion (option). */
+    getItemProps: (params: {
+        item: SearchHit;
+        index: number;
+        userProps?: HTMLAttributes<HTMLElement>;
+    }) => AutocompleteItemProps;
+}
+declare function useAutocomplete(options: UseAutocompleteOptions): UseAutocompleteReturn;
+
 declare const DOTS = "...";
 interface UsePaginationParams {
     currentPage: number;
@@ -101,4 +210,4 @@ interface UrlResolverOptions {
 }
 declare function createDefaultUrlResolver(configs: SearchItemConfig[], options?: UrlResolverOptions): UrlResolver;
 
-export { DOTS, SearchContext, SearchItemDefaultUrlResolverProvider, SearchItemUrlResolverProvider, SearchProvider, type SearchProviderProps, type UrlResolver, type UseSearchPaginationReturn, type UseSearchReturn, createDefaultUrlResolver, usePagination, useSearch, useSearchPagination, useUrlResolver };
+export { type AutocompleteInputProps, type AutocompleteItemProps, type AutocompleteListboxProps, DOTS, SearchContext, SearchItemDefaultUrlResolverProvider, SearchItemUrlResolverProvider, SearchProvider, type SearchProviderProps, type UrlResolver, type UseAutocompleteOptions, type UseAutocompleteReturn, type UseSearchPaginationReturn, type UseSearchReturn, createDefaultUrlResolver, useAutocomplete, usePagination, useSearch, useSearchPagination, useUrlResolver };

package/dist/react.d.ts

@@ -1,6 +1,6 @@
 import * as react from 'react';
-import { FC, ReactNode } from 'react';
-import { d as Pagination, S as SearchHit, a as Facets, P as PageSize, F as FacetBy, h as SearchParams, C as CollectionResult, g as SearchItemConfig } from './client-DOew5kqb.js';
+import { FC, ReactNode, InputHTMLAttributes, HTMLAttributes } from 'react';
+import { d as Pagination, S as SearchHit, a as Facets, P as PageSize, h as SearchParams, C as CollectionResult, F as FacetBy, g as SearchItemConfig } from './client-DOew5kqb.js';
 
 interface SearchProviderProps {
     children: ReactNode;
@@ -39,6 +39,18 @@ interface UseSearchReturn {
      *  (App Router slots) instead of it being passed to the provider. */
     registerOrderBy: (id: string, orderBy: unknown) => void;
     unregisterOrderBy: (id: string) => void;
+    /** The search function the provider drives (typo-tolerance wrapper included). Exposed
+     *  so in-engine components (e.g. an autocomplete box) issue the SAME request shape. */
+    performSearch: (params: SearchParams) => Promise<CollectionResult>;
+    /** Fields the query string is matched against (as configured on the engine). */
+    queryBy?: string[];
+    /** Locale the search is scoped to (per-locale collection). */
+    locale?: string;
+    /** Always-applied base `filter_by` string (from the engine's base filters). */
+    baseFilterString?: string;
+    /** The active facet selections as a `performSearch` `filters` object — mirrors the
+     *  main results request so an autocomplete can reproduce the current filtered context. */
+    currentFilters: Record<string, unknown>;
     filterOptions: FacetBy[];
     setFilterOptions: (filters: FacetBy[]) => void;
     /** Additive registration of a single facet option (keyed by fieldKey). Used by facet
@@ -56,6 +68,103 @@ declare const SearchProvider: FC<SearchProviderProps>;
 
 declare function useSearch(): UseSearchReturn;
 
+interface UseAutocompleteOptions {
+    /**
+     * The search function (same signature used by `SearchProvider`). Typically
+     * `createSearchClient(...).performSearch`.
+     */
+    performSearch: (params: SearchParams) => Promise<CollectionResult>;
+    /** Fields to query against (mirrors `SearchProvider`'s `queryBy`). */
+    queryBy?: string[];
+    /** A base Typesense `filter_by` string applied to every request. */
+    baseFilterBy?: string;
+    /** Active facet selections (same `filters` object `SearchProvider` sends), so the
+     *  autocomplete request mirrors the main results' filtered context. */
+    filters?: Record<string, unknown>;
+    /** Locale to scope the search to (per-locale collection). */
+    locale?: string;
+    /** Max number of suggestions to fetch/show. Default: 6. */
+    perPage?: number;
+    /** Minimum number of characters before a request is made. Default: 1. */
+    minQueryLength?: number;
+    /** Debounce, in ms, between the last keystroke and the request. Default: 150. */
+    debounceMs?: number;
+    /** Open the panel as soon as the input is focused (if there is anything to show). Default: false. */
+    openOnFocus?: boolean;
+    /**
+     * Called when a suggestion is chosen (Enter on the active item, or a click). Use this to
+     * navigate to the item's page.
+     */
+    onSelect?: (item: SearchHit) => void;
+    /**
+     * Called when the raw query is submitted (Enter with no active suggestion). Use this to send
+     * the user to a full search-results page.
+     */
+    onSubmit?: (query: string) => void;
+    maxTypos?: number;
+    minLengthFor1Typo?: number;
+    minLengthFor2Typos?: number;
+    typoFallbackThreshold?: number;
+    prioritizeExactMatch?: boolean;
+}
+interface AutocompleteInputProps extends InputHTMLAttributes<HTMLInputElement> {
+    role: 'combobox';
+    'aria-autocomplete': 'list';
+    'aria-expanded': boolean;
+    'aria-controls': string;
+    'aria-activedescendant'?: string;
+    autoComplete: 'off';
+}
+interface AutocompleteListboxProps extends HTMLAttributes<HTMLElement> {
+    role: 'listbox';
+    id: string;
+}
+interface AutocompleteItemProps extends HTMLAttributes<HTMLElement> {
+    role: 'option';
+    id: string;
+    'aria-selected': boolean;
+}
+interface UseAutocompleteReturn {
+    /** Current input value. */
+    query: string;
+    /** Set the input value programmatically (does not trigger `onSubmit`). */
+    setQuery: (value: string) => void;
+    /** The current suggestions (top hits for the query). */
+    suggestions: SearchHit[];
+    /** True while a request is in flight. */
+    isLoading: boolean;
+    /** Whether the suggestions panel should be shown. */
+    isOpen: boolean;
+    /** Index of the keyboard-active suggestion, or -1 when none is active. */
+    activeIndex: number;
+    /** The keyboard-active suggestion, or null. */
+    activeItem: SearchHit | null;
+    /** Open the panel (if there is anything to show). */
+    open: () => void;
+    /** Close the panel and clear the active item. */
+    close: () => void;
+    /** Clear the query, suggestions, and close the panel. */
+    clear: () => void;
+    /** Select a suggestion (fires `onSelect` and closes the panel). */
+    selectItem: (item: SearchHit) => void;
+    /** Props for a `<label>` associated with the input. */
+    getLabelProps: () => {
+        id: string;
+        htmlFor: string;
+    };
+    /** Props for the `<input>` (combobox). Pass-through props are merged, yours win. */
+    getInputProps: (userProps?: InputHTMLAttributes<HTMLInputElement>) => AutocompleteInputProps;
+    /** Props for the suggestions container (listbox). */
+    getListboxProps: (userProps?: HTMLAttributes<HTMLElement>) => AutocompleteListboxProps;
+    /** Props for a single suggestion (option). */
+    getItemProps: (params: {
+        item: SearchHit;
+        index: number;
+        userProps?: HTMLAttributes<HTMLElement>;
+    }) => AutocompleteItemProps;
+}
+declare function useAutocomplete(options: UseAutocompleteOptions): UseAutocompleteReturn;
+
 declare const DOTS = "...";
 interface UsePaginationParams {
     currentPage: number;
@@ -101,4 +210,4 @@ interface UrlResolverOptions {
 }
 declare function createDefaultUrlResolver(configs: SearchItemConfig[], options?: UrlResolverOptions): UrlResolver;
 
-export { DOTS, SearchContext, SearchItemDefaultUrlResolverProvider, SearchItemUrlResolverProvider, SearchProvider, type SearchProviderProps, type UrlResolver, type UseSearchPaginationReturn, type UseSearchReturn, createDefaultUrlResolver, usePagination, useSearch, useSearchPagination, useUrlResolver };
+export { type AutocompleteInputProps, type AutocompleteItemProps, type AutocompleteListboxProps, DOTS, SearchContext, SearchItemDefaultUrlResolverProvider, SearchItemUrlResolverProvider, SearchProvider, type SearchProviderProps, type UrlResolver, type UseAutocompleteOptions, type UseAutocompleteReturn, type UseSearchPaginationReturn, type UseSearchReturn, createDefaultUrlResolver, useAutocomplete, usePagination, useSearch, useSearchPagination, useUrlResolver };