@etoile-dev/react 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Etoile
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,361 @@
+<p align="center">
+  <a href="https://etoile.dev">
+    <img src="https://etoile.dev/assets/logo-black.svg" alt="Étoile" height="32" />
+  </a>
+</p>
+
+<p align="center">
+  <img src="https://etoile.dev/assets/hands-of-god.jpg" alt="Add search to your app in seconds" width="100%" />
+</p>
+
+<h1 align="center">@etoile-dev/react</h1>
+
+<p align="center">
+  <strong>Headless React primitives for search.</strong>
+  <br />
+  Composable. Accessible. Zero styling.
+</p>
+
+<p align="center">
+  <a href="https://etoile.dev">Website</a> · <a href="https://etoile.dev/docs">Documentation</a>
+</p>
+
+---
+
+## About
+
+**@etoile-dev/react** provides headless, composable React components for search powered by [Étoile](https://etoile.dev).
+
+Built on top of [@etoile-dev/client](https://www.npmjs.com/package/@etoile-dev/client), these primitives give you full control over styling while handling state, keyboard navigation, and accessibility.
+
+---
+
+## Philosophy
+
+- **Headless-first** — You control the appearance
+- **Composable** — Build your own search UX
+- **Accessible** — Full ARIA support and keyboard navigation
+- **No magic** — Behavior is predictable and documented
+- **No opinions** — Bring your own styles (or use our optional theme)
+
+---
+
+## Install
+
+```bash
+npm i @etoile-dev/react
+```
+
+---
+
+## Quickstart
+
+```tsx
+import { Search } from "@etoile-dev/react";
+
+export default function App() {
+  return <Search apiKey="your-api-key" collections={["paintings"]} />;
+}
+```
+
+---
+
+## Composable Primitives
+
+For full control, use the headless primitives:
+
+```tsx
+import {
+  SearchRoot,
+  SearchInput,
+  SearchResults,
+  SearchResult,
+} from "@etoile-dev/react";
+
+export default function CustomSearch() {
+  return (
+    <SearchRoot
+      apiKey={process.env.ETOILE_API_KEY}
+      collections={["paintings"]}
+      limit={20}
+    >
+      <SearchInput placeholder="Search paintings..." className="search-input" />
+      
+      <SearchResults className="results-list">
+        {(result) => (
+          <SearchResult className="result-item">
+            <h3>{result.title}</h3>
+            <p>{result.metadata.artist}</p>
+            <small>Score: {result.score.toFixed(2)}</small>
+          </SearchResult>
+        )}
+      </SearchResults>
+    </SearchRoot>
+  );
+}
+```
+
+---
+
+## Styling with data attributes
+
+Each result automatically gets `data-selected` and `data-index` attributes:
+
+```css
+.result-item {
+  padding: 1rem;
+  cursor: pointer;
+}
+
+.result-item[data-selected="true"] {
+  background: #f0f9ff;
+  border-left: 3px solid #0ea5e9;
+}
+```
+
+---
+
+## Default Theme
+
+Import the optional theme for a polished, ready-to-use experience:
+
+```tsx
+import "@etoile-dev/react/styles.css";
+import { Search } from "@etoile-dev/react";
+
+<Search apiKey="your-api-key" collections={["paintings"]} />
+```
+
+That's it! The `etoile-search` class is applied automatically.
+
+### Dark Mode
+
+Add `dark` to the className:
+
+```tsx
+<Search apiKey="your-api-key" collections={["paintings"]} className="dark" />
+
+// Or with SearchRoot
+<SearchRoot apiKey="your-api-key" collections={["paintings"]} className="dark">
+  ...
+</SearchRoot>
+```
+
+### CSS Variables
+
+Customize the theme with CSS variables:
+
+```css
+.etoile-search {
+  --etoile-bg: #ffffff;
+  --etoile-border: #e4e4e7;
+  --etoile-text: #09090b;
+  --etoile-text-muted: #71717a;
+  --etoile-ring: #18181b;
+  --etoile-selected: #f4f4f5;
+  --etoile-radius: 12px;
+}
+```
+
+---
+
+## Headless hook
+
+For complete control, use the `useSearch` hook:
+
+```tsx
+import { useSearch } from "@etoile-dev/react";
+
+function MyCustomSearch() {
+  const { query, setQuery, results, isLoading } = useSearch({
+    apiKey: "your-api-key",
+    collections: ["paintings"],
+  });
+
+  return (
+    <div>
+      <input
+        value={query}
+        onChange={(e) => setQuery(e.target.value)}
+        placeholder="Search paintings..."
+      />
+      {isLoading && <p>Loading...</p>}
+      <ul>
+        {results.map((result) => (
+          <li key={result.external_id}>{result.title}</li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+---
+
+## API
+
+### `<Search>`
+
+Convenience component that composes all primitives.
+
+| Prop           | Type                                          | Required | Default |
+|----------------|-----------------------------------------------|----------|---------|
+| `apiKey`       | `string`                                      | ✓        |         |
+| `collections`  | `string[]`                                    | ✓        |         |
+| `limit`        | `number`                                      |          | `10`    |
+| `renderResult` | `(result: SearchResultData) => React.ReactNode` |          |         |
+
+---
+
+### `<SearchRoot>`
+
+Context provider that manages search state and keyboard navigation.
+
+| Prop          | Type              | Required | Default |
+|---------------|-------------------|----------|---------|
+| `apiKey`      | `string`          | ✓        |         |
+| `collections` | `string[]`        | ✓        |         |
+| `limit`       | `number`          |          | `10`    |
+| `debounceMs`  | `number`          |          | `100`   |
+| `autoFocus`   | `boolean`         |          | `false` |
+| `children`    | `React.ReactNode` | ✓        |         |
+
+---
+
+### `<SearchInput>`
+
+Controlled input with ARIA combobox role.
+
+| Prop          | Type     |
+|---------------|----------|
+| `placeholder` | `string` |
+| `className`   | `string` |
+
+**Keyboard shortcuts:**
+- `ArrowUp` / `ArrowDown` — Navigate results
+- `Enter` — Select active result
+- `Escape` — Clear search
+
+---
+
+### `<SearchResults>`
+
+Results container with ARIA listbox role.
+
+| Prop        | Type                                          | Required |
+|-------------|-----------------------------------------------|----------|
+| `className` | `string`                                      |          |
+| `children`  | `(result: SearchResultData) => React.ReactNode` | ✓        |
+
+---
+
+### `<SearchResult>`
+
+Individual result with ARIA option role.
+
+| Prop        | Type              | Required |
+|-------------|-------------------|----------|
+| `className` | `string`          |          |
+| `children`  | `React.ReactNode` | ✓        |
+
+**Data attributes:**
+- `data-selected="true" | "false"` — Active state
+- `data-index="number"` — Result position
+
+---
+
+### `<SearchResultThumbnail>`
+
+Thumbnail image that auto-detects from `metadata.thumbnailUrl`.
+
+| Prop        | Type     | Required | Default                       |
+|-------------|----------|----------|-------------------------------|
+| `src`       | `string` |          | `metadata.thumbnailUrl`       |
+| `alt`       | `string` |          | `result.title`                |
+| `size`      | `number` |          | `40`                          |
+| `className` | `string` |          |                               |
+
+---
+
+### `<SearchIcon>`
+
+Built-in search magnifying glass SVG icon.
+
+| Prop        | Type     | Required | Default |
+|-------------|----------|----------|---------|
+| `size`      | `number` |          | `18`    |
+| `className` | `string` |          |         |
+
+---
+
+### `<SearchKbd>`
+
+Keyboard shortcut badge.
+
+| Prop        | Type              | Required | Default |
+|-------------|-------------------|----------|---------|
+| `children`  | `React.ReactNode` |          | `⌘K`    |
+| `className` | `string` |          | `etoile-kbd` |
+
+```tsx
+<SearchKbd />           // Shows "⌘K"
+<SearchKbd>/</SearchKbd> // Shows "/"
+```
+
+---
+
+### `useSearch(options)`
+
+Headless hook for complete control.
+
+**Options:**
+
+| Field         | Type       | Required | Default |
+|---------------|------------|----------|---------|
+| `apiKey`      | `string`   | ✓        |         |
+| `collections` | `string[]` | ✓        |         |
+| `limit`       | `number`   |          | `10`    |
+| `debounceMs`  | `number`   |          | `100`   |
+
+**Returns:**
+
+| Field              | Type                       |
+|--------------------|----------------------------|
+| `query`            | `string`                   |
+| `setQuery`         | `(q: string) => void`      |
+| `results`          | `SearchResultData[]`       |
+| `isLoading`        | `boolean`                  |
+| `selectedIndex`    | `number`                   |
+| `setSelectedIndex` | `(i: number) => void`      |
+| `clear`            | `() => void`               |
+
+---
+
+## Types
+
+```ts
+type SearchResultData = {
+  external_id: string;
+  title: string;
+  collection: string;
+  score: number;
+  content?: string;
+  metadata: Record<string, unknown>;
+};
+```
+
+---
+
+## Why @etoile-dev/react?
+
+- **Radix / shadcn-style primitives** — Composable and unstyled
+- **Accessibility built-in** — ARIA roles, keyboard navigation, focus management
+- **Behavior, not appearance** — You own the design
+- **TypeScript-first** — Full type safety
+- **Zero dependencies** — Only React and @etoile-dev/client
+
+---
+
+<p align="center">
+  <a href="https://etoile.dev/docs"><strong>Read the docs →</strong></a>
+</p>

package/dist/Search.d.ts

@@ -0,0 +1,36 @@
+import * as React from "react";
+import type { SearchResultData } from "./types.js";
+export type SearchProps = {
+    /** 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;
+    /** Placeholder text for the search input */
+    placeholder?: string;
+    /** Additional CSS class name (e.g., "dark" for dark mode) */
+    className?: string;
+    /** Custom render function for each result (optional) */
+    renderResult?: (result: SearchResultData) => React.ReactNode;
+};
+/**
+ * All-in-one search component with sensible defaults.
+ *
+ * Provides a complete, polished search experience out of the box including
+ * search icon, keyboard shortcut badge, and result thumbnails. Just import
+ * `@etoile-dev/react/styles.css` for styling - no wrapper needed.
+ *
+ * @param props - Component props
+ *
+ * @example
+ * ```tsx
+ * <Search apiKey="your-api-key" collections={["paintings"]} />
+ * ```
+ *
+ * @example Dark mode
+ * ```tsx
+ * <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;

package/dist/Search.js

@@ -0,0 +1,31 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { SearchRoot } from "./components/SearchRoot.js";
+import { SearchInput } from "./components/SearchInput.js";
+import { SearchResults } from "./components/SearchResults.js";
+import { SearchResult } from "./components/SearchResult.js";
+import { SearchResultThumbnail } from "./components/SearchResultThumbnail.js";
+import { SearchIcon } from "./components/SearchIcon.js";
+import { SearchKbd } from "./components/SearchKbd.js";
+const DefaultResult = (result) => (_jsxs(SearchResult, { children: [_jsx(SearchResultThumbnail, {}), _jsxs("div", { className: "etoile-result-content", children: [_jsx("span", { className: "etoile-result-title", children: result.title }), _jsx("span", { className: "etoile-result-subtitle", children: result.collection })] })] }));
+/**
+ * All-in-one search component with sensible defaults.
+ *
+ * Provides a complete, polished search experience out of the box including
+ * search icon, keyboard shortcut badge, and result thumbnails. Just import
+ * `@etoile-dev/react/styles.css` for styling - no wrapper needed.
+ *
+ * @param props - Component props
+ *
+ * @example
+ * ```tsx
+ * <Search apiKey="your-api-key" collections={["paintings"]} />
+ * ```
+ *
+ * @example Dark mode
+ * ```tsx
+ * <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 })] }));
+};

package/dist/components/SearchIcon.d.ts

@@ -0,0 +1,22 @@
+export type SearchIconProps = {
+    /** Width and height in pixels (default: 18) */
+    size?: number;
+    /** CSS class name for styling */
+    className?: string;
+};
+/**
+ * Search magnifying glass icon.
+ *
+ * A minimal SVG icon that works perfectly with the default theme.
+ *
+ * @param props - Component props
+ *
+ * @example
+ * ```tsx
+ * <div className="etoile-input-wrapper">
+ *   <SearchIcon />
+ *   <SearchInput placeholder="Search..." />
+ * </div>
+ * ```
+ */
+export declare const SearchIcon: ({ size, className }: SearchIconProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/SearchIcon.js

@@ -0,0 +1,17 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Search magnifying glass icon.
+ *
+ * A minimal SVG icon that works perfectly with the default theme.
+ *
+ * @param props - Component props
+ *
+ * @example
+ * ```tsx
+ * <div className="etoile-input-wrapper">
+ *   <SearchIcon />
+ *   <SearchInput placeholder="Search..." />
+ * </div>
+ * ```
+ */
+export const SearchIcon = ({ size = 18, className }) => (_jsxs("svg", { xmlns: "http://www.w3.org/2000/svg", width: size, height: size, viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: 2, strokeLinecap: "round", strokeLinejoin: "round", className: className, "aria-hidden": "true", children: [_jsx("path", { d: "m21 21-4.34-4.34" }), _jsx("circle", { cx: "11", cy: "11", r: "8" })] }));

package/dist/components/SearchInput.d.ts

@@ -0,0 +1,28 @@
+export type SearchInputProps = {
+    /** Placeholder text for the input field */
+    placeholder?: string;
+    /** CSS class name for styling the input */
+    className?: string;
+};
+/**
+ * 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.
+ *
+ * @param props - Component props
+ *
+ * @example
+ * ```tsx
+ * <SearchInput />
+ * ```
+ *
+ * @example With placeholder and styling
+ * ```tsx
+ * <SearchInput
+ *   placeholder="Search paintings..."
+ *   className="px-4 py-2 border rounded-lg"
+ * />
+ * ```
+ */
+export declare const SearchInput: ({ placeholder, className }: SearchInputProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/SearchInput.js

@@ -0,0 +1,35 @@
+import { jsx as _jsx } 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.
+ *
+ * @param props - Component props
+ *
+ * @example
+ * ```tsx
+ * <SearchInput />
+ * ```
+ *
+ * @example With placeholder and styling
+ * ```tsx
+ * <SearchInput
+ *   placeholder="Search paintings..."
+ *   className="px-4 py-2 border rounded-lg"
+ * />
+ * ```
+ */
+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 }));
+};

package/dist/components/SearchKbd.d.ts

@@ -0,0 +1,30 @@
+import * as React from "react";
+export type SearchKbdProps = {
+    /** Keyboard shortcut text (default: "⌘K") */
+    children?: React.ReactNode;
+    /** CSS class name for styling */
+    className?: string;
+};
+/**
+ * Keyboard shortcut badge for search.
+ *
+ * Displays a styled keyboard shortcut indicator. Works with the default theme.
+ *
+ * @param props - Component props
+ *
+ * @example
+ * ```tsx
+ * <div className="etoile-input-wrapper">
+ *   <SearchIcon />
+ *   <SearchInput placeholder="Search..." />
+ *   <SearchKbd />
+ * </div>
+ * ```
+ *
+ * @example Custom shortcut
+ * ```tsx
+ * <SearchKbd>/</SearchKbd>
+ * <SearchKbd>Ctrl K</SearchKbd>
+ * ```
+ */
+export declare const SearchKbd: ({ children, className, }: SearchKbdProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/SearchKbd.js

@@ -0,0 +1,24 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Keyboard shortcut badge for search.
+ *
+ * Displays a styled keyboard shortcut indicator. Works with the default theme.
+ *
+ * @param props - Component props
+ *
+ * @example
+ * ```tsx
+ * <div className="etoile-input-wrapper">
+ *   <SearchIcon />
+ *   <SearchInput placeholder="Search..." />
+ *   <SearchKbd />
+ * </div>
+ * ```
+ *
+ * @example Custom shortcut
+ * ```tsx
+ * <SearchKbd>/</SearchKbd>
+ * <SearchKbd>Ctrl K</SearchKbd>
+ * ```
+ */
+export const SearchKbd = ({ children = "⌘K", className, }) => (_jsx("kbd", { className: className ? `etoile-kbd ${className}` : "etoile-kbd", children: children }));

package/dist/components/SearchResult.d.ts

@@ -0,0 +1,30 @@
+import * as React from "react";
+export type SearchResultProps = {
+    /** CSS class name for styling the result item */
+    className?: string;
+    /** Content to render inside the result */
+    children: React.ReactNode;
+};
+/**
+ * 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.
+ *
+ * @param props - Component props
+ *
+ * @example
+ * ```tsx
+ * <SearchResult>{result.title}</SearchResult>
+ * ```
+ *
+ * @example With selection styling
+ * ```tsx
+ * <SearchResult className="result-item">
+ *   <h3>{result.title}</h3>
+ * </SearchResult>
+ *
+ * // CSS: .result-item[data-selected="true"] { background: #f0f9ff; }
+ * ```
+ */
+export declare const SearchResult: ({ className, children }: SearchResultProps) => import("react/jsx-runtime").JSX.Element | null;

package/dist/components/SearchResult.js

@@ -0,0 +1,39 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as React from "react";
+import { useSearchContext } from "../context/SearchContext.js";
+import { SearchResultIndexContext } from "./SearchResults.js";
+/**
+ * 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.
+ *
+ * @param props - Component props
+ *
+ * @example
+ * ```tsx
+ * <SearchResult>{result.title}</SearchResult>
+ * ```
+ *
+ * @example With selection styling
+ * ```tsx
+ * <SearchResult className="result-item">
+ *   <h3>{result.title}</h3>
+ * </SearchResult>
+ *
+ * // CSS: .result-item[data-selected="true"] { background: #f0f9ff; }
+ * ```
+ */
+export const SearchResult = ({ className, children }) => {
+    const { selectedIndex, registerResult, getResultId } = useSearchContext();
+    const index = React.useContext(SearchResultIndexContext);
+    if (index === null) {
+        return null;
+    }
+    const isSelected = index === selectedIndex;
+    const id = React.useMemo(() => getResultId(index), [getResultId, index]);
+    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 }));
+};