@etoile-dev/react 0.2.3 → 1.0.1

package/dist/components/SearchResults.js

@@ -1,53 +0,0 @@
-import { jsx as _jsx } from "react/jsx-runtime";
-import * as React from "react";
-import { useSearchContext } from "../context/SearchContext.js";
-export const SearchResultIndexContext = React.createContext(null);
-export const SearchResultDataContext = React.createContext(null);
-/**
- * Container component for rendering search results with keyboard navigation.
- *
- * Accepts a render function that receives each result. Automatically hides
- * when query is empty or no results found. Includes ARIA listbox role.
- * Accepts standard div props like onScroll and style.
- *
- * @param props - Component props
- *
- * @example
- * ```tsx
- * <SearchResults>
- *   {(result) => <SearchResult>{result.title}</SearchResult>}
- * </SearchResults>
- * ```
- *
- * @example With styling and metadata
- * ```tsx
- * <SearchResults className="mt-2 border rounded-lg">
- *   {(result) => (
- *     <SearchResult className="p-4 hover:bg-gray-50">
- *       <h3>{result.title}</h3>
- *       <p>{result.metadata?.artist}</p>
- *     </SearchResult>
- *   )}
- * </SearchResults>
- * ```
- */
-export const SearchResults = ({ className, children, ...props }) => {
-    const { query, results, isOpen, selectedIndex, listboxId, getResultNode } = useSearchContext();
-    const listboxRef = React.useRef(null);
-    React.useEffect(() => {
-        if (selectedIndex < 0) {
-            return;
-        }
-        const activeNode = getResultNode(selectedIndex);
-        activeNode?.scrollIntoView({ block: "nearest" });
-        if (activeNode &&
-            listboxRef.current &&
-            listboxRef.current.contains(document.activeElement)) {
-            activeNode.focus();
-        }
-    }, [getResultNode, selectedIndex]);
-    if (!isOpen || query.trim() === "" || results.length === 0) {
-        return null;
-    }
-    return (_jsx("div", { ...props, role: "listbox", id: listboxId, className: className, ref: listboxRef, children: results.map((result, index) => (_jsx(SearchResultIndexContext.Provider, { value: index, children: _jsx(SearchResultDataContext.Provider, { value: result, children: children(result) }) }, result.external_id))) }));
-};

package/dist/components/SearchRoot.d.ts

@@ -1,44 +0,0 @@
-import * as React from "react";
-export type SearchRootProps = {
-    /** Your Étoile API key. Get one at https://etoile.dev */
-    apiKey: string;
-    /** Collections to search in (e.g., ["paintings", "artists"]) */
-    collections: string[];
-    /** Maximum number of results to return (default: 10) */
-    limit?: number;
-    /** Debounce delay in milliseconds before triggering search (default: 100) */
-    debounceMs?: number;
-    /** Whether the search input should be focused on mount (default: false) */
-    autoFocus?: boolean;
-    /** Additional CSS class name (appended to "etoile-search") */
-    className?: string;
-    /** Child components (SearchInput, SearchResults, etc.) */
-    children: React.ReactNode;
-    baseUrl?: string;
-};
-/**
- * Root component for Étoile search that provides context to all child components.
- *
- * Manages search state, keyboard navigation, result selection, and accessibility.
- * Automatically applies `etoile-search` class for styling when using the theme.
- *
- * @param props - Component props
- *
- * @example
- * ```tsx
- * <SearchRoot apiKey="your-api-key" collections={["paintings"]}>
- *   <SearchInput />
- *   <SearchResults>
- *     {(result) => <SearchResult>{result.title}</SearchResult>}
- *   </SearchResults>
- * </SearchRoot>
- * ```
- *
- * @example Dark mode
- * ```tsx
- * <SearchRoot apiKey="your-api-key" collections={["paintings"]} className="dark">
- *   ...
- * </SearchRoot>
- * ```
- */
-export declare const SearchRoot: ({ apiKey, collections, limit, debounceMs, autoFocus, className, children, baseUrl, }: SearchRootProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/SearchRoot.js

@@ -1,132 +0,0 @@
-import { jsx as _jsx } from "react/jsx-runtime";
-import * as React from "react";
-import { SearchProvider } from "../context/SearchContext.js";
-import { useSearch } from "../hooks/useSearch.js";
-/**
- * Root component for Étoile search that provides context to all child components.
- *
- * Manages search state, keyboard navigation, result selection, and accessibility.
- * Automatically applies `etoile-search` class for styling when using the theme.
- *
- * @param props - Component props
- *
- * @example
- * ```tsx
- * <SearchRoot apiKey="your-api-key" collections={["paintings"]}>
- *   <SearchInput />
- *   <SearchResults>
- *     {(result) => <SearchResult>{result.title}</SearchResult>}
- *   </SearchResults>
- * </SearchRoot>
- * ```
- *
- * @example Dark mode
- * ```tsx
- * <SearchRoot apiKey="your-api-key" collections={["paintings"]} className="dark">
- *   ...
- * </SearchRoot>
- * ```
- */
-export const SearchRoot = ({ apiKey, collections, limit, debounceMs, autoFocus = false, className, children, baseUrl, }) => {
-    const search = useSearch({ apiKey, collections, limit, debounceMs, baseUrl });
-    const listboxId = React.useId();
-    const resultRefs = React.useRef(new Map());
-    const rootRef = React.useRef(null);
-    const [isOpen, setOpen] = React.useState(false);
-    // Open the results list whenever results arrive and query is non-empty
-    React.useEffect(() => {
-        if (search.results.length > 0 && search.query.trim() !== "") {
-            setOpen(true);
-        }
-    }, [search.results, search.query]);
-    // Close results when query is cleared
-    React.useEffect(() => {
-        if (search.query.trim() === "") {
-            setOpen(false);
-        }
-    }, [search.query]);
-    // Click-outside: close results when clicking outside the root element
-    React.useEffect(() => {
-        const handlePointerDown = (event) => {
-            if (rootRef.current &&
-                event.target instanceof Node &&
-                !rootRef.current.contains(event.target)) {
-                setOpen(false);
-            }
-        };
-        document.addEventListener("pointerdown", handlePointerDown);
-        return () => document.removeEventListener("pointerdown", handlePointerDown);
-    }, []);
-    // Focus-out: close results when focus leaves the component entirely
-    const handleFocusOut = (event) => {
-        if (rootRef.current &&
-            event.relatedTarget instanceof Node &&
-            !rootRef.current.contains(event.relatedTarget)) {
-            setOpen(false);
-        }
-        // relatedTarget is null when focus moves outside the document (e.g. address bar)
-        if (!event.relatedTarget) {
-            setOpen(false);
-        }
-    };
-    const registerResult = (index, node) => {
-        resultRefs.current.set(index, node);
-    };
-    const getResultNode = (index) => {
-        return resultRefs.current.get(index) ?? null;
-    };
-    const getResultId = (index) => `${listboxId}-option-${index}`;
-    const selectActiveResult = () => {
-        if (search.selectedIndex < 0) {
-            return;
-        }
-        const node = getResultNode(search.selectedIndex);
-        if (node && "click" in node) {
-            node.click();
-        }
-    };
-    const handleKeyDown = (event) => {
-        if (event.key === "ArrowDown") {
-            event.preventDefault();
-            setOpen(true);
-            search.setSelectedIndex(search.selectedIndex + 1);
-            return;
-        }
-        if (event.key === "ArrowUp") {
-            event.preventDefault();
-            setOpen(true);
-            search.setSelectedIndex(search.selectedIndex - 1);
-            return;
-        }
-        if (event.key === "Enter") {
-            if (search.selectedIndex >= 0) {
-                event.preventDefault();
-                selectActiveResult();
-            }
-            return;
-        }
-        if (event.key === "Escape") {
-            event.preventDefault();
-            // First Escape closes results, second clears the query
-            if (isOpen) {
-                setOpen(false);
-            }
-            else {
-                search.clear();
-            }
-        }
-    };
-    const value = React.useMemo(() => ({
-        ...search,
-        isOpen,
-        setOpen,
-        listboxId,
-        getResultId,
-        registerResult,
-        getResultNode,
-        selectActiveResult,
-        handleKeyDown,
-        autoFocus,
-    }), [search, isOpen, listboxId, autoFocus]);
-    return (_jsx(SearchProvider, { value: value, children: _jsx("div", { ref: rootRef, className: className ? `etoile-search ${className}` : "etoile-search", onBlur: handleFocusOut, children: children }) }));
-};

package/dist/context/SearchContext.d.ts

@@ -1,55 +0,0 @@
-import * as React from "react";
-import type { SearchResultData } from "../types.js";
-/**
- * Internal context value for search state and controls.
- * @internal
- */
-type SearchContextValue = {
-    query: string;
-    setQuery: (q: string) => void;
-    results: SearchResultData[];
-    isLoading: boolean;
-    selectedIndex: number;
-    setSelectedIndex: (i: number) => void;
-    clear: () => void;
-    /** Whether the results list is currently open/visible */
-    isOpen: boolean;
-    /** Open or close the results list */
-    setOpen: (open: boolean) => void;
-    listboxId: string;
-    getResultId: (index: number) => string;
-    registerResult: (index: number, node: HTMLElement | null) => void;
-    getResultNode: (index: number) => HTMLElement | null;
-    selectActiveResult: () => void;
-    handleKeyDown: (event: React.KeyboardEvent<HTMLInputElement>) => void;
-    autoFocus: boolean;
-};
-export declare const SearchProvider: React.Provider<SearchContextValue | null>;
-/**
- * Hook to access search context from child components.
- *
- * Must be used within SearchRoot component. Provides access to search state,
- * results, loading status, and keyboard navigation controls.
- *
- * @throws Error if used outside of SearchRoot
- *
- * @example
- * ```tsx
- * import { useSearchContext } from "@etoile-dev/react";
- *
- * function CustomSearchComponent() {
- *   const { query, results, isLoading, clear } = useSearchContext();
- *
- *   return (
- *     <div>
- *       <p>Searching for: {query}</p>
- *       {isLoading && <span>Loading...</span>}
- *       <button onClick={clear}>Clear</button>
- *       <p>Found {results.length} results</p>
- *     </div>
- *   );
- * }
- * ```
- */
-export declare const useSearchContext: () => SearchContextValue;
-export {};

package/dist/context/SearchContext.js

@@ -1,36 +0,0 @@
-import * as React from "react";
-const SearchContext = React.createContext(null);
-export const SearchProvider = SearchContext.Provider;
-/**
- * Hook to access search context from child components.
- *
- * Must be used within SearchRoot component. Provides access to search state,
- * results, loading status, and keyboard navigation controls.
- *
- * @throws Error if used outside of SearchRoot
- *
- * @example
- * ```tsx
- * import { useSearchContext } from "@etoile-dev/react";
- *
- * function CustomSearchComponent() {
- *   const { query, results, isLoading, clear } = useSearchContext();
- *
- *   return (
- *     <div>
- *       <p>Searching for: {query}</p>
- *       {isLoading && <span>Loading...</span>}
- *       <button onClick={clear}>Clear</button>
- *       <p>Found {results.length} results</p>
- *     </div>
- *   );
- * }
- * ```
- */
-export const useSearchContext = () => {
-    const ctx = React.useContext(SearchContext);
-    if (!ctx) {
-        throw new Error("Search components must be used within SearchRoot.");
-    }
-    return ctx;
-};

package/dist/hooks/useSearch.d.ts

@@ -1,56 +0,0 @@
-import type { SearchResultData } from "../types.js";
-export type UseSearchOptions = {
-    /** Your Étoile API key. Get one at https://etoile.dev */
-    apiKey: string;
-    /** Collections to search in (e.g., ["paintings", "artists"]) */
-    collections: string[];
-    /** Maximum number of results to return (default: 10) */
-    limit?: number;
-    /** Debounce delay in milliseconds before triggering search (default: 100) */
-    debounceMs?: number;
-    baseUrl?: string;
-};
-export type UseSearchReturn = {
-    /** Current search query string */
-    query: string;
-    /** Update the search query */
-    setQuery: (q: string) => void;
-    /** Array of search results */
-    results: SearchResultData[];
-    /** Whether a search is currently in progress */
-    isLoading: boolean;
-    /** Index of the currently selected result (-1 if none) */
-    selectedIndex: number;
-    /** Set the selected result index */
-    setSelectedIndex: (i: number) => void;
-    /** Clear the search query and results */
-    clear: () => void;
-};
-/**
- * React hook for managing search state with automatic debouncing and API integration.
- *
- * Handles search queries, debouncing, API calls, loading states, and result management.
- * Works seamlessly with Étoile's search API.
- *
- * @param options - Search configuration options
- * @returns Search state and control functions
- *
- * @example
- * ```tsx
- * const { query, setQuery, results } = useSearch({
- *   apiKey: "your-api-key",
- *   collections: ["paintings"],
- * });
- * ```
- *
- * @example With all options
- * ```tsx
- * const { query, setQuery, results, isLoading, clear } = useSearch({
- *   apiKey: "your-api-key",
- *   collections: ["paintings", "artists"],
- *   limit: 20,
- *   debounceMs: 150,
- * });
- * ```
- */
-export declare const useSearch: ({ apiKey, collections, limit, debounceMs, baseUrl, }: UseSearchOptions) => UseSearchReturn;

package/dist/hooks/useSearch.js

@@ -1,116 +0,0 @@
-import * as React from "react";
-import { Etoile } from "@etoile-dev/client";
-const clampIndex = (index, length) => {
-    if (length <= 0) {
-        return -1;
-    }
-    if (index < 0) {
-        return 0;
-    }
-    if (index > length - 1) {
-        return length - 1;
-    }
-    return index;
-};
-/**
- * React hook for managing search state with automatic debouncing and API integration.
- *
- * Handles search queries, debouncing, API calls, loading states, and result management.
- * Works seamlessly with Étoile's search API.
- *
- * @param options - Search configuration options
- * @returns Search state and control functions
- *
- * @example
- * ```tsx
- * const { query, setQuery, results } = useSearch({
- *   apiKey: "your-api-key",
- *   collections: ["paintings"],
- * });
- * ```
- *
- * @example With all options
- * ```tsx
- * const { query, setQuery, results, isLoading, clear } = useSearch({
- *   apiKey: "your-api-key",
- *   collections: ["paintings", "artists"],
- *   limit: 20,
- *   debounceMs: 150,
- * });
- * ```
- */
-export const useSearch = ({ apiKey, collections, limit = 10, debounceMs = 100, baseUrl, }) => {
-    const [query, setQuery] = React.useState("");
-    const [debouncedQuery, setDebouncedQuery] = React.useState("");
-    const [results, setResults] = React.useState([]);
-    const [isLoading, setIsLoading] = React.useState(false);
-    const [selectedIndex, setSelectedIndexState] = React.useState(-1);
-    const client = React.useMemo(() => new Etoile({ apiKey, baseUrl }), [apiKey, baseUrl]);
-    React.useEffect(() => {
-        const handle = setTimeout(() => {
-            setDebouncedQuery(query);
-        }, debounceMs);
-        return () => clearTimeout(handle);
-    }, [query, debounceMs]);
-    React.useEffect(() => {
-        let isActive = true;
-        if (debouncedQuery.trim() === "") {
-            setResults([]);
-            setIsLoading(false);
-            return () => {
-                isActive = false;
-            };
-        }
-        const runSearch = async () => {
-            setIsLoading(true);
-            try {
-                const response = await client.search({
-                    collections,
-                    query: debouncedQuery,
-                    limit,
-                });
-                if (!isActive) {
-                    return;
-                }
-                setResults(Array.isArray(response.results) ? response.results : []);
-            }
-            catch {
-                if (!isActive) {
-                    return;
-                }
-                setResults([]);
-            }
-            finally {
-                if (isActive) {
-                    setIsLoading(false);
-                }
-            }
-        };
-        runSearch();
-        return () => {
-            isActive = false;
-        };
-    }, [client, collections, debouncedQuery, limit]);
-    React.useEffect(() => {
-        setSelectedIndexState((current) => clampIndex(current, results.length));
-    }, [results.length]);
-    const setSelectedIndex = React.useCallback((index) => {
-        setSelectedIndexState(clampIndex(index, results.length));
-    }, [results.length]);
-    const clear = React.useCallback(() => {
-        setQuery("");
-        setDebouncedQuery("");
-        setResults([]);
-        setIsLoading(false);
-        setSelectedIndexState(-1);
-    }, []);
-    return {
-        query,
-        setQuery,
-        results,
-        isLoading,
-        selectedIndex,
-        setSelectedIndex,
-        clear,
-    };
-};