@etoile-dev/react 0.2.0 → 0.2.2

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/components/SearchInput.d.ts

@@ -1,14 +1,16 @@
+import * as React from "react";
 export type SearchInputProps = {
     /** Placeholder text for the input field */
     placeholder?: string;
     /** CSS class name for styling the input */
     className?: string;
-};
+} & React.InputHTMLAttributes<HTMLInputElement>;
 /**
  * Search input component with built-in keyboard navigation and accessibility.
  *
  * Integrates with SearchRoot context to provide debouncing and keyboard controls
  * (ArrowUp, ArrowDown, Enter, Escape). Implements ARIA combobox pattern.
+ * Accepts standard input props like aria-label and autoComplete.
  *
  * @param props - Component props
  *
@@ -25,4 +27,4 @@ export type SearchInputProps = {
  * />
  * ```
  */
-export declare const SearchInput: ({ placeholder, className }: SearchInputProps) => import("react/jsx-runtime").JSX.Element;
+export declare const SearchInput: ({ placeholder, className, ...props }: SearchInputProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/SearchInput.js

@@ -1,10 +1,11 @@
-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.
  *
  * Integrates with SearchRoot context to provide debouncing and keyboard controls
  * (ArrowUp, ArrowDown, Enter, Escape). Implements ARIA combobox pattern.
+ * Accepts standard input props like aria-label and autoComplete.
  *
  * @param props - Component props
  *
@@ -21,15 +22,38 @@ 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 }));
+export const SearchInput = ({ placeholder, className, ...props }) => {
+    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", { ...props, 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) => {
+                    props.onChange?.(event);
+                    const nextValue = event.target.value;
+                    setQuery(nextValue);
+                    if (nextValue.trim() !== "") {
+                        setSelectedIndex(0);
+                    }
+                }, onFocus: (event) => {
+                    props.onFocus?.(event);
+                    if (!event.defaultPrevented && query.trim() !== "" && results.length > 0) {
+                        setOpen(true);
+                    }
+                }, onKeyDown: (event) => {
+                    props.onKeyDown?.(event);
+                    if (!event.defaultPrevented) {
+                        handleKeyDown(event);
+                    }
+                } }), _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/SearchResult.d.ts

@@ -4,12 +4,13 @@ export type SearchResultProps = {
     className?: string;
     /** Content to render inside the result */
     children: React.ReactNode;
-};
+} & React.HTMLAttributes<HTMLDivElement>;
 /**
  * Individual search result item with selection state and keyboard navigation.
  *
  * Manages selection state and accessibility attributes. Provides `data-selected`
  * attribute for styling the active result. Must be used inside SearchResults.
+ * Accepts standard div props like onClick for custom behavior.
  *
  * @param props - Component props
  *
@@ -27,4 +28,4 @@ export type SearchResultProps = {
  * // CSS: .result-item[data-selected="true"] { background: #f0f9ff; }
  * ```
  */
-export declare const SearchResult: ({ className, children }: SearchResultProps) => import("react/jsx-runtime").JSX.Element | null;
+export declare const SearchResult: ({ className, children, ...props }: SearchResultProps) => import("react/jsx-runtime").JSX.Element | null;

package/dist/components/SearchResult.js

@@ -7,6 +7,7 @@ import { SearchResultIndexContext } from "./SearchResults.js";
  *
  * Manages selection state and accessibility attributes. Provides `data-selected`
  * attribute for styling the active result. Must be used inside SearchResults.
+ * Accepts standard div props like onClick for custom behavior.
  *
  * @param props - Component props
  *
@@ -24,7 +25,7 @@ import { SearchResultIndexContext } from "./SearchResults.js";
  * // CSS: .result-item[data-selected="true"] { background: #f0f9ff; }
  * ```
  */
-export const SearchResult = ({ className, children }) => {
+export const SearchResult = ({ className, children, ...props }) => {
     const { selectedIndex, registerResult, getResultId } = useSearchContext();
     const index = React.useContext(SearchResultIndexContext);
     if (index === null) {
@@ -35,5 +36,5 @@ export const SearchResult = ({ className, children }) => {
     const setRef = React.useCallback((node) => {
         registerResult(index, node);
     }, [index, registerResult]);
-    return (_jsx("div", { ref: setRef, id: id, role: "option", "aria-selected": isSelected, "data-selected": isSelected ? "true" : "false", "data-index": index, tabIndex: isSelected ? 0 : -1, className: className, children: children }));
+    return (_jsx("div", { ...props, ref: setRef, id: id, role: "option", "aria-selected": isSelected, "data-selected": isSelected ? "true" : "false", "data-index": index, tabIndex: isSelected ? 0 : -1, className: className, children: children }));
 };

package/dist/components/SearchResultThumbnail.d.ts

@@ -1,3 +1,4 @@
+import * as React from "react";
 export type SearchResultThumbnailProps = {
     /** Image source URL (defaults to result.metadata.thumbnailUrl) */
     src?: string;
@@ -7,12 +8,13 @@ export type SearchResultThumbnailProps = {
     size?: number;
     /** CSS class name for styling */
     className?: string;
-};
+} & React.ImgHTMLAttributes<HTMLImageElement>;
 /**
  * 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.
+ * Accepts standard img props like loading and decoding.
  *
  * @param props - Component props
  *
@@ -33,4 +35,4 @@ export type SearchResultThumbnailProps = {
  * <SearchResultThumbnail size={48} className="rounded-full" />
  * ```
  */
-export declare const SearchResultThumbnail: ({ src, alt, size, className, }: SearchResultThumbnailProps) => import("react/jsx-runtime").JSX.Element | null;
+export declare const SearchResultThumbnail: ({ src, alt, size, className, ...props }: SearchResultThumbnailProps) => import("react/jsx-runtime").JSX.Element | null;

package/dist/components/SearchResultThumbnail.js

@@ -6,6 +6,7 @@ import { SearchResultDataContext } from "./SearchResults.js";
  *
  * Automatically uses `metadata.thumbnailUrl` if available. Returns null
  * if no image source is found. Must be used inside SearchResults.
+ * Accepts standard img props like loading and decoding.
  *
  * @param props - Component props
  *
@@ -26,12 +27,12 @@ import { SearchResultDataContext } from "./SearchResults.js";
  * <SearchResultThumbnail size={48} className="rounded-full" />
  * ```
  */
-export const SearchResultThumbnail = ({ src, alt, size = 40, className, }) => {
+export const SearchResultThumbnail = ({ src, alt, size = 40, className, ...props }) => {
     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 }));
+    return (_jsx("img", { ...props, src: imageSrc, alt: imageAlt, width: size, height: size, className: className, draggable: false }));
 };

package/dist/components/SearchResults.d.ts

@@ -5,7 +5,7 @@ export type SearchResultsProps = {
     className?: string;
     /** Render function that receives each search result */
     children: (result: SearchResultData) => React.ReactNode;
-};
+} & Omit<React.HTMLAttributes<HTMLDivElement>, "children">;
 export declare const SearchResultIndexContext: React.Context<number | null>;
 export declare const SearchResultDataContext: React.Context<SearchResultData | null>;
 /**
@@ -13,6 +13,7 @@ export declare const SearchResultDataContext: React.Context<SearchResultData | n
  *
  * 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
  *
@@ -35,4 +36,4 @@ export declare const SearchResultDataContext: React.Context<SearchResultData | n
  * </SearchResults>
  * ```
  */
-export declare const SearchResults: ({ className, children }: SearchResultsProps) => import("react/jsx-runtime").JSX.Element | null;
+export declare const SearchResults: ({ className, children, ...props }: SearchResultsProps) => import("react/jsx-runtime").JSX.Element | null;

package/dist/components/SearchResults.js

@@ -8,6 +8,7 @@ export const SearchResultDataContext = React.createContext(null);
  *
  * 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
  *
@@ -30,8 +31,8 @@ export const SearchResultDataContext = React.createContext(null);
  * </SearchResults>
  * ```
  */
-export const SearchResults = ({ className, children }) => {
-    const { query, results, selectedIndex, listboxId, getResultNode } = useSearchContext();
+export const SearchResults = ({ className, children, ...props }) => {
+    const { query, results, isOpen, selectedIndex, listboxId, getResultNode } = useSearchContext();
     const listboxRef = React.useRef(null);
     React.useEffect(() => {
         if (selectedIndex < 0) {
@@ -45,8 +46,8 @@ 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))) }));
+    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.js

@@ -31,6 +31,44 @@ export const SearchRoot = ({ apiKey, collections, limit, debounceMs, autoFocus =
     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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@etoile-dev/react",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Official React primitives for Étoile - Headless, composable search components",
   "keywords": [
     "etoile",