@etoile-dev/react 0.1.1

package/dist/components/SearchResultThumbnail.d.ts

@@ -0,0 +1,36 @@
+export type SearchResultThumbnailProps = {
+    /** Image source URL (defaults to result.metadata.thumbnailUrl) */
+    src?: string;
+    /** Alt text for the image (defaults to result.title) */
+    alt?: string;
+    /** Width and height in pixels (default: 40) */
+    size?: number;
+    /** CSS class name for styling */
+    className?: string;
+};
+/**
+ * Thumbnail image for search results with automatic source detection.
+ *
+ * Automatically uses `metadata.thumbnailUrl` if available. Returns null
+ * if no image source is found. Must be used inside SearchResults.
+ *
+ * @param props - Component props
+ *
+ * @example
+ * ```tsx
+ * <SearchResults>
+ *   {(result) => (
+ *     <SearchResult>
+ *       <SearchResultThumbnail />
+ *       <span>{result.title}</span>
+ *     </SearchResult>
+ *   )}
+ * </SearchResults>
+ * ```
+ *
+ * @example With custom size and styling
+ * ```tsx
+ * <SearchResultThumbnail size={48} className="rounded-full" />
+ * ```
+ */
+export declare const SearchResultThumbnail: ({ src, alt, size, className, }: SearchResultThumbnailProps) => import("react/jsx-runtime").JSX.Element | null;

package/dist/components/SearchResultThumbnail.js

@@ -0,0 +1,37 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as React from "react";
+import { SearchResultDataContext } from "./SearchResults.js";
+/**
+ * Thumbnail image for search results with automatic source detection.
+ *
+ * Automatically uses `metadata.thumbnailUrl` if available. Returns null
+ * if no image source is found. Must be used inside SearchResults.
+ *
+ * @param props - Component props
+ *
+ * @example
+ * ```tsx
+ * <SearchResults>
+ *   {(result) => (
+ *     <SearchResult>
+ *       <SearchResultThumbnail />
+ *       <span>{result.title}</span>
+ *     </SearchResult>
+ *   )}
+ * </SearchResults>
+ * ```
+ *
+ * @example With custom size and styling
+ * ```tsx
+ * <SearchResultThumbnail size={48} className="rounded-full" />
+ * ```
+ */
+export const SearchResultThumbnail = ({ src, alt, size = 40, className, }) => {
+    const result = React.useContext(SearchResultDataContext);
+    const imageSrc = src ?? result?.metadata?.thumbnailUrl;
+    const imageAlt = alt ?? result?.title ?? "";
+    if (!imageSrc) {
+        return null;
+    }
+    return (_jsx("img", { src: imageSrc, alt: imageAlt, width: size, height: size, className: className, draggable: false }));
+};

package/dist/components/SearchResults.d.ts

@@ -0,0 +1,38 @@
+import * as React from "react";
+import type { SearchResultData } from "../types.js";
+export type SearchResultsProps = {
+    /** CSS class name for the results container */
+    className?: string;
+    /** Render function that receives each search result */
+    children: (result: SearchResultData) => React.ReactNode;
+};
+export declare const SearchResultIndexContext: React.Context<number | null>;
+export declare const SearchResultDataContext: React.Context<SearchResultData | 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.
+ *
+ * @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 declare const SearchResults: ({ className, children }: SearchResultsProps) => import("react/jsx-runtime").JSX.Element | null;

package/dist/components/SearchResults.js

@@ -0,0 +1,52 @@
+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.
+ *
+ * @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 }) => {
+    const { query, results, 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 (query.trim() === "" || results.length === 0) {
+        return null;
+    }
+    return (_jsx("div", { 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

@@ -0,0 +1,43 @@
+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;
+};
+/**
+ * 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, }: SearchRootProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/SearchRoot.js

@@ -0,0 +1,84 @@
+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, }) => {
+    const search = useSearch({ apiKey, collections, limit, debounceMs });
+    const listboxId = React.useId();
+    const resultRefs = React.useRef(new Map());
+    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();
+            search.setSelectedIndex(search.selectedIndex + 1);
+            return;
+        }
+        if (event.key === "ArrowUp") {
+            event.preventDefault();
+            search.setSelectedIndex(search.selectedIndex - 1);
+            return;
+        }
+        if (event.key === "Enter") {
+            if (search.selectedIndex >= 0) {
+                event.preventDefault();
+                selectActiveResult();
+            }
+            return;
+        }
+        if (event.key === "Escape") {
+            event.preventDefault();
+            search.clear();
+        }
+    };
+    const value = React.useMemo(() => ({
+        ...search,
+        listboxId,
+        getResultId,
+        registerResult,
+        getResultNode,
+        selectActiveResult,
+        handleKeyDown,
+        autoFocus,
+    }), [search, listboxId, autoFocus]);
+    return (_jsx(SearchProvider, { value: value, children: _jsx("div", { className: className ? `etoile-search ${className}` : "etoile-search", children: children }) }));
+};

package/dist/context/SearchContext.d.ts

@@ -0,0 +1,51 @@
+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;
+    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

@@ -0,0 +1,36 @@
+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

@@ -0,0 +1,55 @@
+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;
+};
+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, }: UseSearchOptions) => UseSearchReturn;

package/dist/hooks/useSearch.js

@@ -0,0 +1,116 @@
+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, }) => {
+    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);
+    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 client = new Etoile({ apiKey });
+                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;
+        };
+    }, [apiKey, 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,
+    };
+};

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+export { SearchRoot } from "./components/SearchRoot.js";
+export { SearchInput } from "./components/SearchInput.js";
+export { SearchResults } from "./components/SearchResults.js";
+export { SearchResult } from "./components/SearchResult.js";
+export { SearchResultThumbnail } from "./components/SearchResultThumbnail.js";
+export { SearchIcon } from "./components/SearchIcon.js";
+export { SearchKbd } from "./components/SearchKbd.js";
+export { Search } from "./Search.js";
+export { useSearch } from "./hooks/useSearch.js";
+export { useSearchContext } from "./context/SearchContext.js";
+export type { SearchResultData } from "./types.js";
+export type { SearchRootProps } from "./components/SearchRoot.js";
+export type { SearchInputProps } from "./components/SearchInput.js";
+export type { SearchResultsProps } from "./components/SearchResults.js";
+export type { SearchResultProps } from "./components/SearchResult.js";
+export type { SearchResultThumbnailProps } from "./components/SearchResultThumbnail.js";
+export type { SearchIconProps } from "./components/SearchIcon.js";
+export type { SearchKbdProps } from "./components/SearchKbd.js";
+export type { SearchProps } from "./Search.js";
+export type { UseSearchOptions, UseSearchReturn } from "./hooks/useSearch.js";

package/dist/index.js

@@ -0,0 +1,12 @@
+// Components
+export { SearchRoot } from "./components/SearchRoot.js";
+export { SearchInput } from "./components/SearchInput.js";
+export { SearchResults } from "./components/SearchResults.js";
+export { SearchResult } from "./components/SearchResult.js";
+export { SearchResultThumbnail } from "./components/SearchResultThumbnail.js";
+export { SearchIcon } from "./components/SearchIcon.js";
+export { SearchKbd } from "./components/SearchKbd.js";
+export { Search } from "./Search.js";
+// Hooks
+export { useSearch } from "./hooks/useSearch.js";
+export { useSearchContext } from "./context/SearchContext.js";