@etoile-dev/react 0.2.3 → 1.0.0

package/dist/Searchbar.d.ts

@@ -0,0 +1,315 @@
+/**
+ * Searchbar — primary export of `@etoile-dev/react`.
+ *
+ * This module exposes three APIs:
+ *
+ * 1. **Convenience wrapper**: `<Searchbar />` (Etoile-powered, live data).
+ *    Pass `apiKey` + `collections` and it handles query state, fetch, loading,
+ *    error, and default rendering.
+ *
+ * 2. **Convenience modal**: `<SearchModal />` (Etoile-powered command palette).
+ *    Pass `apiKey` + `collections` and it handles trigger, portal, overlay,
+ *    content, and live results.
+ *
+ * 3. **Headless primitives**: `Searchbar.Root`, `Searchbar.Input`,
+ *    `Searchbar.List`, `Searchbar.Item`, etc. are UI-only primitives with no
+ *    built-in data fetching. Bring your own data layer.
+ */
+import * as React from "react";
+import type { SearchFilter, SearchResult } from "@etoile-dev/client";
+import type { SearchbarRootProps } from "./primitives/Root.js";
+export type SearchbarProps = {
+    /** Your Etoile API key. Get one at https://etoile.dev */
+    apiKey: string;
+    /** Collections to search in (e.g., ["paintings", "artists"]) */
+    collections: string[];
+    /** Maximum results to return (default: 10) */
+    limit?: number;
+    /** Number of results to skip for pagination (default: 0) */
+    offset?: number;
+    /** Debounce delay in ms (default: 100) */
+    debounceMs?: number;
+    /** Placeholder for the search input (default: "Search…") */
+    placeholder?: string;
+    /**
+     * Explicit metadata filters applied to results.
+     * Mutually exclusive with `autoFilters`.
+     *
+     * @example
+     * ```tsx
+     * filters={[{ key: "artist", operator: "eq", value: "Vincent van Gogh" }]}
+     * ```
+     */
+    filters?: SearchFilter[];
+    /**
+     * When `true`, the AI extracts filters from the query automatically.
+     * Mutually exclusive with `filters`.
+     */
+    autoFilters?: boolean;
+    /**
+     * Custom render function for each result item.
+     * Return a `Searchbar.Item` with a stable `value`.
+     */
+    renderItem?: (result: SearchResult) => React.ReactNode;
+    /** Called when an item is selected. Receives the result's `external_id`. */
+    onSelect?: (value: string) => void;
+    baseUrl?: string;
+} & Omit<SearchbarRootProps, "isLoading" | "error" | "search" | "onSearchChange" | "children" | "onSelect">;
+export type SearchModalProps = {
+    /** Your Etoile API key. Get one at https://etoile.dev */
+    apiKey: string;
+    /** Collections to search in (e.g., ["paintings", "artists"]) */
+    collections: string[];
+    /** Maximum results to return (default: 10) */
+    limit?: number;
+    /** Number of results to skip for pagination (default: 0) */
+    offset?: number;
+    /** Debounce delay in ms (default: 100) */
+    debounceMs?: number;
+    /** Placeholder for the modal input (default: "Search…") */
+    placeholder?: string;
+    /**
+     * Explicit metadata filters applied to results.
+     * Mutually exclusive with `autoFilters`.
+     */
+    filters?: SearchFilter[];
+    /**
+     * When `true`, the AI extracts filters from the query automatically.
+     * Mutually exclusive with `filters`.
+     */
+    autoFilters?: boolean;
+    /**
+     * Global keyboard shortcut that opens the modal.
+     * Defaults to `"mod+k"` (⌘K on Mac / Ctrl+K elsewhere).
+     */
+    hotkey?: string;
+    /** Accessible label for modal content (default: "Search") */
+    modalLabel?: string;
+    /**
+     * Custom render function for each result item.
+     * Return a `Searchbar.Item` with a stable `value`.
+     */
+    renderItem?: (result: SearchResult) => React.ReactNode;
+    /** Called when an item is selected. Receives the result's `external_id`. */
+    onSelect?: (value: string) => void;
+    baseUrl?: string;
+} & Omit<SearchbarRootProps, "isLoading" | "error" | "search" | "onSearchChange" | "children" | "onSelect" | "hotkey">;
+/**
+ * All-in-one command palette powered by Etoile.
+ *
+ * Handles portal, overlay, modal content, and live search results.
+ * Includes built-in open/close logic and defaults to `hotkey="mod+k"`.
+ * Import `@etoile-dev/react/styles.css` for the default theme.
+ *
+ * @example Basic usage
+ * ```tsx
+ * <SearchModal apiKey="your-api-key" collections={["paintings"]} />
+ * ```
+ *
+ * @example With filters
+ * ```tsx
+ * <SearchModal
+ *   apiKey={process.env.ETOILE_API_KEY!}
+ *   collections={["paintings"]}
+ *   filters={[{ key: "artist", operator: "eq", value: "Vincent van Gogh" }]}
+ * />
+ * ```
+ *
+ * @example With custom rendering
+ * ```tsx
+ * <SearchModal
+ *   apiKey={process.env.ETOILE_API_KEY!}
+ *   collections={["paintings", "artists"]}
+ *   hotkey="mod+/"
+ *   renderItem={(result) => (
+ *     <Searchbar.Item value={result.external_id} label={result.title}>
+ *       <Searchbar.Thumbnail />
+ *       <div>
+ *         <strong>{result.title}</strong>
+ *         <span>{String(result.metadata?.artist ?? "")}</span>
+ *       </div>
+ *     </Searchbar.Item>
+ *   )}
+ * />
+ * ```
+ */
+export declare const SearchModal: React.ForwardRefExoticComponent<{
+    /** Your Etoile API key. Get one at https://etoile.dev */
+    apiKey: string;
+    /** Collections to search in (e.g., ["paintings", "artists"]) */
+    collections: string[];
+    /** Maximum results to return (default: 10) */
+    limit?: number;
+    /** Number of results to skip for pagination (default: 0) */
+    offset?: number;
+    /** Debounce delay in ms (default: 100) */
+    debounceMs?: number;
+    /** Placeholder for the modal input (default: "Search…") */
+    placeholder?: string;
+    /**
+     * Explicit metadata filters applied to results.
+     * Mutually exclusive with `autoFilters`.
+     */
+    filters?: SearchFilter[];
+    /**
+     * When `true`, the AI extracts filters from the query automatically.
+     * Mutually exclusive with `filters`.
+     */
+    autoFilters?: boolean;
+    /**
+     * Global keyboard shortcut that opens the modal.
+     * Defaults to `"mod+k"` (⌘K on Mac / Ctrl+K elsewhere).
+     */
+    hotkey?: string;
+    /** Accessible label for modal content (default: "Search") */
+    modalLabel?: string;
+    /**
+     * Custom render function for each result item.
+     * Return a `Searchbar.Item` with a stable `value`.
+     */
+    renderItem?: (result: SearchResult) => React.ReactNode;
+    /** Called when an item is selected. Receives the result's `external_id`. */
+    onSelect?: (value: string) => void;
+    baseUrl?: string;
+} & Omit<SearchbarRootProps, "isLoading" | "error" | "children" | "onSelect" | "search" | "onSearchChange" | "hotkey"> & React.RefAttributes<HTMLDivElement>>;
+export declare const Searchbar: React.ForwardRefExoticComponent<{
+    /** Your Etoile API key. Get one at https://etoile.dev */
+    apiKey: string;
+    /** Collections to search in (e.g., ["paintings", "artists"]) */
+    collections: string[];
+    /** Maximum results to return (default: 10) */
+    limit?: number;
+    /** Number of results to skip for pagination (default: 0) */
+    offset?: number;
+    /** Debounce delay in ms (default: 100) */
+    debounceMs?: number;
+    /** Placeholder for the search input (default: "Search…") */
+    placeholder?: string;
+    /**
+     * Explicit metadata filters applied to results.
+     * Mutually exclusive with `autoFilters`.
+     *
+     * @example
+     * ```tsx
+     * filters={[{ key: "artist", operator: "eq", value: "Vincent van Gogh" }]}
+     * ```
+     */
+    filters?: SearchFilter[];
+    /**
+     * When `true`, the AI extracts filters from the query automatically.
+     * Mutually exclusive with `filters`.
+     */
+    autoFilters?: boolean;
+    /**
+     * Custom render function for each result item.
+     * Return a `Searchbar.Item` with a stable `value`.
+     */
+    renderItem?: (result: SearchResult) => React.ReactNode;
+    /** Called when an item is selected. Receives the result's `external_id`. */
+    onSelect?: (value: string) => void;
+    baseUrl?: string;
+} & Omit<SearchbarRootProps, "isLoading" | "error" | "children" | "onSelect" | "search" | "onSearchChange"> & React.RefAttributes<HTMLDivElement>> & {
+    Root: React.ForwardRefExoticComponent<{
+        open?: boolean;
+        defaultOpen?: boolean;
+        onOpenChange?: (open: boolean) => void;
+        search?: string;
+        defaultSearch?: string;
+        onSearchChange?: (search: string) => void;
+        value?: string | null;
+        defaultValue?: string | null;
+        onValueChange?: (value: string | null) => void;
+        isLoading?: boolean;
+        error?: unknown;
+        hotkey?: string;
+        hotkeyBehavior?: "focus" | "toggle";
+        onSelect?: (value: string) => void;
+        children: React.ReactNode;
+        className?: string;
+        asChild?: boolean;
+    } & Omit<React.HTMLAttributes<HTMLDivElement>, "onSelect"> & React.RefAttributes<HTMLDivElement>>;
+    Input: React.ForwardRefExoticComponent<{
+        placeholder?: string;
+        className?: string;
+        asChild?: boolean;
+    } & Omit<React.InputHTMLAttributes<HTMLInputElement>, "value" | "onChange"> & React.RefAttributes<HTMLInputElement>>;
+    List: React.ForwardRefExoticComponent<{
+        className?: string;
+        asChild?: boolean;
+        children: React.ReactNode;
+    } & Omit<React.HTMLAttributes<HTMLDivElement>, "role"> & React.RefAttributes<HTMLDivElement>>;
+    Item: React.ForwardRefExoticComponent<{
+        value: string;
+        label?: string;
+        disabled?: boolean;
+        onSelect?: (value: string) => void;
+        children: React.ReactNode;
+        className?: string;
+        asChild?: boolean;
+    } & Omit<React.HTMLAttributes<HTMLDivElement>, "onSelect"> & React.RefAttributes<HTMLDivElement>>;
+    Group: React.ForwardRefExoticComponent<{
+        label?: string;
+        className?: string;
+        asChild?: boolean;
+        children: React.ReactNode;
+    } & React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
+    Separator: React.ForwardRefExoticComponent<{
+        className?: string;
+        asChild?: boolean;
+    } & React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
+    Empty: React.ForwardRefExoticComponent<{
+        children?: React.ReactNode;
+        className?: string;
+        asChild?: boolean;
+    } & Omit<React.HTMLAttributes<HTMLDivElement>, "role"> & React.RefAttributes<HTMLDivElement>>;
+    Loading: React.ForwardRefExoticComponent<{
+        children?: React.ReactNode;
+        className?: string;
+        asChild?: boolean;
+    } & Omit<React.HTMLAttributes<HTMLDivElement>, "role"> & React.RefAttributes<HTMLDivElement>>;
+    Error: React.ForwardRefExoticComponent<{
+        children?: React.ReactNode | ((error: unknown) => React.ReactNode);
+        className?: string;
+        asChild?: boolean;
+    } & Omit<React.HTMLAttributes<HTMLDivElement>, "children" | "role"> & React.RefAttributes<HTMLDivElement>>;
+    Portal: {
+        ({ container, children }: import("./primitives/Portal.js").SearchbarPortalProps): React.ReactPortal | null;
+        displayName: string;
+    };
+    Overlay: React.ForwardRefExoticComponent<{
+        className?: string;
+        asChild?: boolean;
+    } & React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
+    Content: React.ForwardRefExoticComponent<{
+        "aria-label"?: string;
+        className?: string;
+        asChild?: boolean;
+        children: React.ReactNode;
+    } & Omit<React.HTMLAttributes<HTMLDivElement>, "role"> & React.RefAttributes<HTMLDivElement>>;
+    Modal: React.ForwardRefExoticComponent<{
+        "aria-label"?: string;
+    } & Omit<SearchbarRootProps, "asChild"> & React.RefAttributes<HTMLDivElement>>;
+    ModalInput: React.ForwardRefExoticComponent<{
+        placeholder?: string;
+        icon?: React.ReactNode | null;
+        kbd?: React.ReactNode | null;
+        className?: string;
+    } & Omit<React.HTMLAttributes<HTMLDivElement>, "children"> & React.RefAttributes<HTMLDivElement>>;
+    Trigger: React.ForwardRefExoticComponent<{
+        children?: React.ReactNode;
+        className?: string;
+        asChild?: boolean;
+    } & React.ButtonHTMLAttributes<HTMLButtonElement> & React.RefAttributes<HTMLButtonElement>>;
+    Icon: {
+        ({ size, className, ...props }: import("./primitives/Icon.js").SearchbarIconProps): import("react/jsx-runtime").JSX.Element;
+        displayName: string;
+    };
+    Kbd: {
+        ({ children, className, ...props }: import("./primitives/Kbd.js").SearchbarKbdProps): import("react/jsx-runtime").JSX.Element;
+        displayName: string;
+    };
+    Thumbnail: {
+        ({ src, alt, size, className, ...props }: import("./primitives/Thumbnail.js").SearchbarThumbnailProps): import("react/jsx-runtime").JSX.Element | null;
+        displayName: string;
+    };
+};

package/dist/Searchbar.js

@@ -0,0 +1,207 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Searchbar — primary export of `@etoile-dev/react`.
+ *
+ * This module exposes three APIs:
+ *
+ * 1. **Convenience wrapper**: `<Searchbar />` (Etoile-powered, live data).
+ *    Pass `apiKey` + `collections` and it handles query state, fetch, loading,
+ *    error, and default rendering.
+ *
+ * 2. **Convenience modal**: `<SearchModal />` (Etoile-powered command palette).
+ *    Pass `apiKey` + `collections` and it handles trigger, portal, overlay,
+ *    content, and live results.
+ *
+ * 3. **Headless primitives**: `Searchbar.Root`, `Searchbar.Input`,
+ *    `Searchbar.List`, `Searchbar.Item`, etc. are UI-only primitives with no
+ *    built-in data fetching. Bring your own data layer.
+ */
+import * as React from "react";
+import { Root } from "./primitives/Root.js";
+import { Input } from "./primitives/Input.js";
+import { List } from "./primitives/List.js";
+import { Item } from "./primitives/Item.js";
+import { Group } from "./primitives/Group.js";
+import { Separator } from "./primitives/Separator.js";
+import { Empty } from "./primitives/Empty.js";
+import { Loading } from "./primitives/Loading.js";
+import { Error as ErrorPrimitive } from "./primitives/Error.js";
+import { Portal } from "./primitives/Portal.js";
+import { Overlay } from "./primitives/Overlay.js";
+import { Content } from "./primitives/Content.js";
+import { Modal } from "./primitives/Modal.js";
+import { ModalInput } from "./primitives/ModalInput.js";
+import { Trigger } from "./primitives/Trigger.js";
+import { Icon } from "./primitives/Icon.js";
+import { Kbd } from "./primitives/Kbd.js";
+import { Thumbnail } from "./primitives/Thumbnail.js";
+import { useEtoileSearch } from "./hooks/useEtoileSearch.js";
+import { SearchbarItemDataContext } from "./context.js";
+/** Format hotkey string for display (e.g. "mod+k" → "⌘K" on Mac, "Ctrl+K" elsewhere). */
+function formatHotkeyLabel(hotkey) {
+    const isMac = typeof navigator !== "undefined" && /mac|darwin/i.test(navigator.platform);
+    const parts = hotkey.toLowerCase().trim().split("+");
+    const key = parts[parts.length - 1];
+    const keyChar = key === "slash" ? "/" : key;
+    const mods = parts.slice(0, -1);
+    const modLabels = [];
+    if (mods.includes("mod"))
+        modLabels.push(isMac ? "⌘" : "Ctrl");
+    if (mods.includes("ctrl"))
+        modLabels.push("Ctrl");
+    if (mods.includes("alt"))
+        modLabels.push(isMac ? "⌥" : "Alt");
+    if (mods.includes("shift"))
+        modLabels.push(isMac ? "⇧" : "Shift");
+    const keyDisplay = keyChar === "/" || keyChar.length > 1 ? keyChar : keyChar.toUpperCase();
+    return modLabels.length > 0 ? `${modLabels.join("")}${keyDisplay}` : keyDisplay;
+}
+/**
+ * All-in-one search component powered by Etoile.
+ *
+ * Handles data fetching, debounce, keyboard navigation, and ARIA wiring.
+ * No default hotkey; pass `hotkey="/"` (or `hotkey="mod+k"`) if you want a global shortcut.
+ * Import `@etoile-dev/react/styles.css` for the default theme.
+ *
+ * @example
+ * ```tsx
+ * import "@etoile-dev/react/styles.css";
+ * import { Searchbar } from "@etoile-dev/react";
+ *
+ * <Searchbar apiKey="your-api-key" collections={["paintings"]} />
+ * ```
+ *
+ * @example With filters and custom rendering
+ * ```tsx
+ * <Searchbar
+ *   apiKey={process.env.ETOILE_API_KEY!}
+ *   collections={["paintings"]}
+ *   filters={[{ key: "artist", operator: "eq", value: "Vincent van Gogh" }]}
+ *   onSelect={(id) => router.push(`/painting/${id}`)}
+ *   renderItem={(result) => (
+ *     <Searchbar.Item value={result.external_id} label={result.title}>
+ *       <Searchbar.Thumbnail />
+ *       <div>
+ *         <strong>{result.title}</strong>
+ *         <span>{String(result.metadata?.year ?? "")}</span>
+ *       </div>
+ *     </Searchbar.Item>
+ *   )}
+ * />
+ * ```
+ *
+ * @example Headless primitives (no Etoile dependency)
+ * ```tsx
+ * <Searchbar.Root onSelect={handleSelect}>
+ *   <Searchbar.Input placeholder="Search paintings…" />
+ *   <Searchbar.List>
+ *     {paintings.map((p) => (
+ *       <Searchbar.Item key={p.id} value={p.id} label={p.title}>
+ *         {p.title}
+ *       </Searchbar.Item>
+ *     ))}
+ *     <Searchbar.Empty>No results.</Searchbar.Empty>
+ *   </Searchbar.List>
+ * </Searchbar.Root>
+ * ```
+ */
+const SearchbarWrapper = React.forwardRef(({ apiKey, collections, limit, offset, debounceMs, placeholder = "Search…", filters, autoFilters, renderItem, onSelect, baseUrl, hotkey, className, ...rootProps }, ref) => {
+    const [query, setQuery] = React.useState("");
+    const { results, isLoading, error } = useEtoileSearch({
+        apiKey,
+        collections,
+        query,
+        limit,
+        offset,
+        debounceMs,
+        filters,
+        autoFilters,
+        baseUrl,
+    });
+    return (_jsxs(Root, { ...rootProps, ref: ref, hotkey: hotkey, hotkeyBehavior: hotkey ? "focus" : undefined, search: query, onSearchChange: setQuery, isLoading: isLoading, error: error ?? undefined, onSelect: onSelect, className: className
+            ? `etoile-search ${className}`
+            : "etoile-search", children: [_jsxs("div", { "data-slot": "searchbar-input-row", children: [_jsx(Icon, {}), _jsx(Input, { placeholder: placeholder }), hotkey ? _jsx(Kbd, { children: formatHotkeyLabel(hotkey) }) : null] }), _jsxs(List, { children: [results.map((result) => renderItem ? (
+                    // User's custom renderer — wrap in data context so Thumbnail works
+                    _jsx(SearchbarItemDataContext.Provider, { value: result, children: renderItem(result) }, result.external_id)) : (_jsx(DefaultItem, { result: result }, result.external_id))), _jsxs(Empty, { children: ["No results found for ", _jsxs("span", { "data-slot": "searchbar-empty-query", children: ["\"", query, "\""] })] }), _jsx(Loading, {}), _jsx(ErrorPrimitive, {})] })] }));
+});
+SearchbarWrapper.displayName = "Searchbar";
+/**
+ * All-in-one command palette powered by Etoile.
+ *
+ * Handles portal, overlay, modal content, and live search results.
+ * Includes built-in open/close logic and defaults to `hotkey="mod+k"`.
+ * Import `@etoile-dev/react/styles.css` for the default theme.
+ *
+ * @example Basic usage
+ * ```tsx
+ * <SearchModal apiKey="your-api-key" collections={["paintings"]} />
+ * ```
+ *
+ * @example With filters
+ * ```tsx
+ * <SearchModal
+ *   apiKey={process.env.ETOILE_API_KEY!}
+ *   collections={["paintings"]}
+ *   filters={[{ key: "artist", operator: "eq", value: "Vincent van Gogh" }]}
+ * />
+ * ```
+ *
+ * @example With custom rendering
+ * ```tsx
+ * <SearchModal
+ *   apiKey={process.env.ETOILE_API_KEY!}
+ *   collections={["paintings", "artists"]}
+ *   hotkey="mod+/"
+ *   renderItem={(result) => (
+ *     <Searchbar.Item value={result.external_id} label={result.title}>
+ *       <Searchbar.Thumbnail />
+ *       <div>
+ *         <strong>{result.title}</strong>
+ *         <span>{String(result.metadata?.artist ?? "")}</span>
+ *       </div>
+ *     </Searchbar.Item>
+ *   )}
+ * />
+ * ```
+ */
+export const SearchModal = React.forwardRef(({ apiKey, collections, limit, offset, debounceMs, placeholder = "Search…", filters, autoFilters, hotkey = "mod+k", modalLabel = "Search", renderItem, onSelect, baseUrl, className, ...rootProps }, ref) => {
+    const [query, setQuery] = React.useState("");
+    const { results, isLoading, error } = useEtoileSearch({
+        apiKey,
+        collections,
+        query,
+        limit,
+        offset,
+        debounceMs,
+        filters,
+        autoFilters,
+        baseUrl,
+    });
+    return (_jsxs(Modal, { ...rootProps, ref: ref, hotkey: hotkey, search: query, onSearchChange: setQuery, isLoading: isLoading, error: error ?? undefined, onSelect: onSelect, className: className
+            ? `etoile-search ${className}`
+            : "etoile-search", "aria-label": modalLabel, children: [_jsx(ModalInput, { placeholder: placeholder }), _jsxs(List, { children: [results.map((result) => renderItem ? (_jsx(SearchbarItemDataContext.Provider, { value: result, children: renderItem(result) }, result.external_id)) : (_jsx(DefaultItem, { result: result }, result.external_id))), _jsxs(Empty, { children: ["No results found for ", _jsxs("span", { "data-slot": "searchbar-empty-query", children: ["\"", query, "\""] })] }), _jsx(Loading, {}), _jsx(ErrorPrimitive, {})] })] }));
+});
+SearchModal.displayName = "SearchModal";
+// ─── Default item renderer ────────────────────────────────────────────────────
+const DefaultItem = ({ result }) => (_jsx(SearchbarItemDataContext.Provider, { value: result, children: _jsxs(Item, { value: result.external_id, label: result.title, children: [_jsx(Thumbnail, {}), _jsxs("div", { "data-slot": "searchbar-result-content", children: [_jsx("span", { "data-slot": "searchbar-result-title", children: result.title }), _jsx("span", { "data-slot": "searchbar-result-subtitle", children: result.collection })] })] }) }));
+// ─── Namespace assembly ───────────────────────────────────────────────────────
+export const Searchbar = Object.assign(SearchbarWrapper, {
+    Root,
+    Input,
+    List,
+    Item,
+    Group,
+    Separator,
+    Empty,
+    Loading,
+    Error: ErrorPrimitive,
+    Portal,
+    Overlay,
+    Content,
+    Modal,
+    ModalInput,
+    Trigger,
+    Icon,
+    Kbd,
+    Thumbnail,
+});

package/dist/context.d.ts

@@ -0,0 +1,57 @@
+import * as React from "react";
+import type { SearchbarStore, SearchbarState } from "./store.js";
+export type SearchbarContextValue = {
+    store: SearchbarStore;
+    /** Stable listbox DOM id — wired to aria-controls on Input */
+    listId: string;
+    /**
+     * Unique id for the Root instance. Used as `data-searchbar-root` on every
+     * DOM node that belongs to this searchbar (including portaled content) so
+     * the click-outside handler can correctly ignore clicks inside portals.
+     */
+    rootId: string;
+    /** Optional Root className forwarded to portaled Content/Overlay. */
+    rootClassName?: string;
+    /** Whether search is controlled (Input must not mutate store) */
+    isSearchControlled?: boolean;
+    /** Called when query changes (for controlled mode, Input calls this) */
+    onSearchChange?: (query: string) => void;
+    /** Ref for the Trigger — Content restores focus here on close */
+    triggerRef?: React.RefObject<HTMLElement | null>;
+    /** Derive a stable DOM id for a given item value */
+    getItemId: (value: string) => string;
+    /** Trigger selection of an item by value — handles callbacks + state update */
+    onSelect: (value: string) => void;
+    /** Set open state — respects controlled mode (Overlay/Escape use this) */
+    setOpen: (open: boolean) => void;
+    /** Keyboard handler — Input calls this so portal-rendered Inputs get navigation */
+    handleKeyDown: (event: React.KeyboardEvent<HTMLElement>) => void;
+    /** Register an item's DOM node — called by Item on mount/unmount */
+    registerItem: (meta: {
+        value: string;
+        label: string;
+        disabled: boolean;
+        node: HTMLElement | null;
+        onSelect?: (value: string) => void;
+    }) => void;
+    /** Unregister an item on unmount */
+    unregisterItem: (value: string) => void;
+};
+export declare const SearchbarProvider: React.Provider<SearchbarContextValue | null>;
+export declare function useSearchbarContext(): SearchbarContextValue;
+/**
+ * Subscribe to a slice of the searchbar store.
+ * Re-renders only when the selected slice changes (reference equality).
+ *
+ * @example
+ * const query = useSearchbarStore(ctx.store, (s) => s.query);
+ */
+export declare function useSearchbarStore<T>(store: SearchbarStore, selector: (state: SearchbarState) => T): T;
+/** Convenience: read a slice within a component that already has context */
+export declare function useSearchbarState<T>(selector: (state: SearchbarState) => T): T;
+/** When true, List hides when query is empty (command palette mode) */
+export declare const SearchbarHideListWhenQueryEmptyContext: React.Context<boolean>;
+/** Context for the item currently being rendered (set by Searchbar.Item) */
+export declare const SearchbarItemContext: React.Context<string | null>;
+/** Context providing the raw SearchResult when rendered via the Etoile wrapper */
+export declare const SearchbarItemDataContext: React.Context<Record<string, any> | null>;

package/dist/context.js

@@ -0,0 +1,32 @@
+import * as React from "react";
+const SearchbarContext = React.createContext(null);
+export const SearchbarProvider = SearchbarContext.Provider;
+export function useSearchbarContext() {
+    const ctx = React.useContext(SearchbarContext);
+    if (!ctx) {
+        throw new Error("Searchbar primitives must be used within Searchbar.Root.");
+    }
+    return ctx;
+}
+/**
+ * Subscribe to a slice of the searchbar store.
+ * Re-renders only when the selected slice changes (reference equality).
+ *
+ * @example
+ * const query = useSearchbarStore(ctx.store, (s) => s.query);
+ */
+export function useSearchbarStore(store, selector) {
+    return React.useSyncExternalStore(store.subscribe, () => selector(store.getState()), () => selector(store.getState()));
+}
+/** Convenience: read a slice within a component that already has context */
+export function useSearchbarState(selector) {
+    const { store } = useSearchbarContext();
+    return useSearchbarStore(store, selector);
+}
+/** When true, List hides when query is empty (command palette mode) */
+export const SearchbarHideListWhenQueryEmptyContext = React.createContext(false);
+/** Context for the item currently being rendered (set by Searchbar.Item) */
+export const SearchbarItemContext = React.createContext(null);
+/** Context providing the raw SearchResult when rendered via the Etoile wrapper */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const SearchbarItemDataContext = React.createContext(null);