@etoile-dev/react 0.1.2 → 0.2.1

package/README.md

@@ -254,7 +254,7 @@ Controlled input with ARIA combobox role.
 **Keyboard shortcuts:**
 - `ArrowUp` / `ArrowDown` — Navigate results
 - `Enter` — Select active result
-- `Escape` — Clear search
+- `Escape` — Close results (press again to clear)
 
 ---
 
@@ -369,7 +369,7 @@ type SearchResultData = {
 ## Why @etoile-dev/react?
 
 - **Radix / shadcn-style primitives** — Composable and unstyled
-- **Accessibility built-in** — ARIA roles, keyboard navigation, focus management
+- **Accessibility built-in** — ARIA combobox, keyboard navigation, focus management, click-outside dismiss
 - **Behavior, not appearance** — You own the design
 - **TypeScript-first** — Full type safety
 - **Zero dependencies** — Only React and @etoile-dev/client

package/dist/Search.d.ts

@@ -13,6 +13,7 @@ export type SearchProps = {
     className?: string;
     /** Custom render function for each result (optional) */
     renderResult?: (result: SearchResultData) => React.ReactNode;
+    baseUrl?: string;
 };
 /**
  * All-in-one search component with sensible defaults.
@@ -33,4 +34,4 @@ export type SearchProps = {
  * <Search apiKey="your-api-key" collections={["paintings"]} className="dark" />
  * ```
  */
-export declare const Search: ({ apiKey, collections, limit, placeholder, className, renderResult, }: SearchProps) => import("react/jsx-runtime").JSX.Element;
+export declare const Search: ({ apiKey, collections, limit, placeholder, className, renderResult, baseUrl, }: SearchProps) => import("react/jsx-runtime").JSX.Element;

package/dist/Search.js

@@ -26,6 +26,6 @@ const DefaultResult = (result) => (_jsxs(SearchResult, { children: [_jsx(SearchR
  * <Search apiKey="your-api-key" collections={["paintings"]} className="dark" />
  * ```
  */
-export const Search = ({ apiKey, collections, limit, placeholder = "Search...", className, renderResult, }) => {
-    return (_jsxs(SearchRoot, { apiKey: apiKey, collections: collections, limit: limit, className: className, children: [_jsxs("div", { className: "etoile-input-wrapper", children: [_jsx(SearchIcon, {}), _jsx(SearchInput, { placeholder: placeholder }), _jsx(SearchKbd, {})] }), _jsx(SearchResults, { children: renderResult ?? DefaultResult })] }));
+export const Search = ({ apiKey, collections, limit, placeholder = "Search...", className, renderResult, baseUrl, }) => {
+    return (_jsxs(SearchRoot, { apiKey: apiKey, collections: collections, limit: limit, className: className, baseUrl: baseUrl, children: [_jsxs("div", { className: "etoile-input-wrapper", children: [_jsx(SearchIcon, {}), _jsx(SearchInput, { placeholder: placeholder }), _jsx(SearchKbd, {})] }), _jsx(SearchResults, { children: renderResult ?? DefaultResult })] }));
 };

package/dist/components/SearchInput.js

@@ -1,4 +1,4 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { useSearchContext } from "../context/SearchContext.js";
 /**
  * Search input component with built-in keyboard navigation and accessibility.
@@ -22,14 +22,30 @@ import { useSearchContext } from "../context/SearchContext.js";
  * ```
  */
 export const SearchInput = ({ placeholder, className }) => {
-    const { query, setQuery, results, selectedIndex, setSelectedIndex, listboxId, getResultId, handleKeyDown, autoFocus, } = useSearchContext();
-    const hasResults = results.length > 0;
-    const activeId = selectedIndex >= 0 && hasResults ? getResultId(selectedIndex) : undefined;
-    return (_jsx("input", { type: "text", placeholder: placeholder, className: className, value: query, autoFocus: autoFocus, role: "combobox", "aria-expanded": hasResults, "aria-controls": listboxId, "aria-activedescendant": activeId, onChange: (event) => {
-            const nextValue = event.target.value;
-            setQuery(nextValue);
-            if (nextValue.trim() !== "") {
-                setSelectedIndex(0);
-            }
-        }, onKeyDown: handleKeyDown }));
+    const { query, setQuery, results, isOpen, setOpen, selectedIndex, setSelectedIndex, listboxId, getResultId, handleKeyDown, autoFocus, } = useSearchContext();
+    const showResults = isOpen && results.length > 0;
+    const activeId = selectedIndex >= 0 && showResults ? getResultId(selectedIndex) : undefined;
+    return (_jsxs(_Fragment, { children: [_jsx("input", { type: "text", placeholder: placeholder, className: className, value: query, autoFocus: autoFocus, role: "combobox", "aria-expanded": showResults, "aria-controls": listboxId, "aria-activedescendant": activeId, "aria-autocomplete": "list", onChange: (event) => {
+                    const nextValue = event.target.value;
+                    setQuery(nextValue);
+                    if (nextValue.trim() !== "") {
+                        setSelectedIndex(0);
+                    }
+                }, onFocus: () => {
+                    if (query.trim() !== "" && results.length > 0) {
+                        setOpen(true);
+                    }
+                }, onKeyDown: handleKeyDown }), _jsx("div", { role: "status", "aria-live": "polite", "aria-atomic": "true", style: {
+                    position: "absolute",
+                    width: 1,
+                    height: 1,
+                    padding: 0,
+                    margin: -1,
+                    overflow: "hidden",
+                    clip: "rect(0, 0, 0, 0)",
+                    whiteSpace: "nowrap",
+                    border: 0,
+                }, children: showResults
+                    ? `${results.length} result${results.length === 1 ? "" : "s"} available`
+                    : "" })] }));
 };

package/dist/components/SearchResults.js

@@ -31,7 +31,7 @@ export const SearchResultDataContext = React.createContext(null);
  * ```
  */
 export const SearchResults = ({ className, children }) => {
-    const { query, results, selectedIndex, listboxId, getResultNode } = useSearchContext();
+    const { query, results, isOpen, selectedIndex, listboxId, getResultNode } = useSearchContext();
     const listboxRef = React.useRef(null);
     React.useEffect(() => {
         if (selectedIndex < 0) {
@@ -45,7 +45,7 @@ export const SearchResults = ({ className, children }) => {
             activeNode.focus();
         }
     }, [getResultNode, selectedIndex]);
-    if (query.trim() === "" || results.length === 0) {
+    if (!isOpen || 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

@@ -14,6 +14,7 @@ export type SearchRootProps = {
     className?: string;
     /** Child components (SearchInput, SearchResults, etc.) */
     children: React.ReactNode;
+    baseUrl?: string;
 };
 /**
  * Root component for Étoile search that provides context to all child components.
@@ -40,4 +41,4 @@ export type SearchRootProps = {
  * </SearchRoot>
  * ```
  */
-export declare const SearchRoot: ({ apiKey, collections, limit, debounceMs, autoFocus, className, children, }: SearchRootProps) => import("react/jsx-runtime").JSX.Element;
+export declare const SearchRoot: ({ apiKey, collections, limit, debounceMs, autoFocus, className, children, baseUrl, }: SearchRootProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/SearchRoot.js

@@ -27,10 +27,48 @@ import { useSearch } from "../hooks/useSearch.js";
  * </SearchRoot>
  * ```
  */
-export const SearchRoot = ({ apiKey, collections, limit, debounceMs, autoFocus = false, className, children, }) => {
-    const search = useSearch({ apiKey, collections, limit, debounceMs });
+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);
     };
@@ -50,11 +88,13 @@ export const SearchRoot = ({ apiKey, collections, limit, debounceMs, autoFocus =
     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;
         }
@@ -67,11 +107,19 @@ export const SearchRoot = ({ apiKey, collections, limit, debounceMs, autoFocus =
         }
         if (event.key === "Escape") {
             event.preventDefault();
-            search.clear();
+            // 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,
@@ -79,6 +127,6 @@ export const SearchRoot = ({ apiKey, collections, limit, debounceMs, autoFocus =
         selectActiveResult,
         handleKeyDown,
         autoFocus,
-    }), [search, listboxId, autoFocus]);
-    return (_jsx(SearchProvider, { value: value, children: _jsx("div", { className: className ? `etoile-search ${className}` : "etoile-search", children: children }) }));
+    }), [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

@@ -12,6 +12,10 @@ type SearchContextValue = {
     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;

package/dist/hooks/useSearch.d.ts

@@ -8,6 +8,7 @@ export type UseSearchOptions = {
     limit?: number;
     /** Debounce delay in milliseconds before triggering search (default: 100) */
     debounceMs?: number;
+    baseUrl?: string;
 };
 export type UseSearchReturn = {
     /** Current search query string */
@@ -52,4 +53,4 @@ export type UseSearchReturn = {
  * });
  * ```
  */
-export declare const useSearch: ({ apiKey, collections, limit, debounceMs, }: UseSearchOptions) => UseSearchReturn;
+export declare const useSearch: ({ apiKey, collections, limit, debounceMs, baseUrl, }: UseSearchOptions) => UseSearchReturn;

package/dist/hooks/useSearch.js

@@ -39,12 +39,13 @@ const clampIndex = (index, length) => {
  * });
  * ```
  */
-export const useSearch = ({ apiKey, collections, limit = 10, debounceMs = 100, }) => {
+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);
@@ -63,7 +64,6 @@ export const useSearch = ({ apiKey, collections, limit = 10, debounceMs = 100, }
         const runSearch = async () => {
             setIsLoading(true);
             try {
-                const client = new Etoile({ apiKey });
                 const response = await client.search({
                     collections,
                     query: debouncedQuery,
@@ -90,7 +90,7 @@ export const useSearch = ({ apiKey, collections, limit = 10, debounceMs = 100, }
         return () => {
             isActive = false;
         };
-    }, [apiKey, collections, debouncedQuery, limit]);
+    }, [client, collections, debouncedQuery, limit]);
     React.useEffect(() => {
         setSelectedIndexState((current) => clampIndex(current, results.length));
     }, [results.length]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@etoile-dev/react",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "Official React primitives for Étoile - Headless, composable search components",
   "keywords": [
     "etoile",
@@ -49,10 +49,10 @@
     "react": ">=18"
   },
   "dependencies": {
-    "@etoile-dev/client": "^0.1.0"
+    "@etoile-dev/client": "^0.2.0"
   },
   "devDependencies": {
     "@types/react": "^18.0.0",
     "typescript": "^5.0.0"
   }
-}
+}