@etoile-dev/react 0.2.3 → 1.0.0

package/dist/types.d.ts

@@ -1,33 +1,5 @@
 /**
- * Search result data returned from Étoile API.
- *
- * @example
- * ```ts
- * const result: SearchResultData = {
- *   external_id: "starry-night",
- *   title: "The Starry Night",
- *   collection: "paintings",
- *   score: 0.95,
- *   content: "A swirling night sky over a village...",
- *   metadata: {
- *     artist: "Vincent van Gogh",
- *     year: 1889,
- *     url: "https://example.com/starry-night"
- *   }
- * };
- * ```
+ * @deprecated Use `SearchResult` from `@etoile-dev/client` instead.
+ * This alias will be removed in a future major version.
  */
-export type SearchResultData = {
-    /** Unique identifier for the result */
-    external_id: string;
-    /** Title of the result */
-    title: string;
-    /** Collection this result belongs to */
-    collection: string;
-    /** Relevance score (0-1, higher is more relevant) */
-    score: number;
-    /** Text content of the result */
-    content?: string;
-    /** Custom metadata attached to the result */
-    metadata: Record<string, unknown>;
-};
+export type { SearchResult as SearchResultData } from "@etoile-dev/client";

package/dist/utils/composeRefs.d.ts

@@ -0,0 +1,12 @@
+import * as React from "react";
+type ReactRef<T> = React.RefCallback<T> | React.RefObject<T> | React.MutableRefObject<T> | null | undefined;
+/**
+ * Merges multiple refs into a single callback ref.
+ * Useful for combining a forwarded ref with an internal ref.
+ */
+export declare function composeRefs<T>(...refs: ReactRef<T>[]): React.RefCallback<T>;
+/**
+ * Returns a stable composed ref via useMemo.
+ */
+export declare function useComposeRefs<T>(...refs: ReactRef<T>[]): React.RefCallback<T>;
+export {};

package/dist/utils/composeRefs.js

@@ -0,0 +1,27 @@
+import * as React from "react";
+function assignRef(ref, value) {
+    if (!ref)
+        return;
+    if (typeof ref === "function") {
+        ref(value);
+    }
+    else {
+        ref.current = value;
+    }
+}
+/**
+ * Merges multiple refs into a single callback ref.
+ * Useful for combining a forwarded ref with an internal ref.
+ */
+export function composeRefs(...refs) {
+    return (node) => {
+        refs.forEach((ref) => assignRef(ref, node));
+    };
+}
+/**
+ * Returns a stable composed ref via useMemo.
+ */
+export function useComposeRefs(...refs) {
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    return React.useMemo(() => composeRefs(...refs), refs);
+}

package/dist/utils/slot.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Slot — enables the `asChild` composition pattern (Radix-style).
+ *
+ * When a component renders `<Slot>`, it merges its own props onto the single
+ * child element instead of rendering its own DOM node. This lets callers swap
+ * out the underlying element while keeping all behavior props (event handlers,
+ * aria attributes, data-* attributes, ref, className…).
+ *
+ * Usage:
+ *   const Button = ({ asChild, ...props }) => {
+ *     const Comp = asChild ? Slot : 'button';
+ *     return <Comp {...props} />;
+ *   };
+ *
+ *   // Consumer:
+ *   <Button asChild><a href="/search">Search</a></Button>
+ *   // Renders: <a href="/search" ...buttonProps>Search</a>
+ */
+import * as React from "react";
+export declare const Slot: React.ForwardRefExoticComponent<{
+    children?: React.ReactNode;
+} & React.HTMLAttributes<HTMLElement> & React.RefAttributes<HTMLElement>>;

package/dist/utils/slot.js

@@ -0,0 +1,58 @@
+/**
+ * Slot — enables the `asChild` composition pattern (Radix-style).
+ *
+ * When a component renders `<Slot>`, it merges its own props onto the single
+ * child element instead of rendering its own DOM node. This lets callers swap
+ * out the underlying element while keeping all behavior props (event handlers,
+ * aria attributes, data-* attributes, ref, className…).
+ *
+ * Usage:
+ *   const Button = ({ asChild, ...props }) => {
+ *     const Comp = asChild ? Slot : 'button';
+ *     return <Comp {...props} />;
+ *   };
+ *
+ *   // Consumer:
+ *   <Button asChild><a href="/search">Search</a></Button>
+ *   // Renders: <a href="/search" ...buttonProps>Search</a>
+ */
+import * as React from "react";
+import { composeRefs } from "./composeRefs.js";
+export const Slot = React.forwardRef(({ children, ...slotProps }, forwardedRef) => {
+    if (!React.isValidElement(children)) {
+        return null;
+    }
+    const child = children;
+    return React.cloneElement(child, {
+        ...mergeProps(slotProps, child.props),
+        ref: forwardedRef
+            ? composeRefs(forwardedRef, child.ref)
+            : child.ref,
+    });
+});
+Slot.displayName = "Slot";
+// Merge Slot props onto child props — child props win for most things,
+// but event handlers and classNames are composed.
+function mergeProps(slotProps, childProps) {
+    const merged = { ...slotProps };
+    for (const key of Object.keys(childProps)) {
+        const slotVal = slotProps[key];
+        const childVal = childProps[key];
+        if (key === "className") {
+            merged[key] = [slotVal, childVal].filter(Boolean).join(" ") || undefined;
+        }
+        else if (key.startsWith("on") &&
+            typeof slotVal === "function" &&
+            typeof childVal === "function") {
+            merged[key] = (...args) => {
+                childVal(...args);
+                slotVal(...args);
+            };
+        }
+        else {
+            // Child prop wins (more specific)
+            merged[key] = childVal !== undefined ? childVal : slotVal;
+        }
+    }
+    return merged;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@etoile-dev/react",
-  "version": "0.2.3",
-  "description": "Official React primitives for Étoile - Headless, composable search components",
+  "version": "1.0.0",
+  "description": "Official React primitives for Etoile - Headless, composable search components",
   "keywords": [
     "etoile",
     "react",
@@ -43,16 +43,20 @@
   "scripts": {
     "build": "tsc && cp src/styles.css dist/styles.css",
     "clean": "rm -rf dist",
-    "prepublishOnly": "npm run clean && npm run build"
+    "prepublishOnly": "npm run clean && npm run build",
+    "playground": "npm run dev --workspace=playground"
   },
+  "workspaces": [
+    "playground"
+  ],
   "peerDependencies": {
     "react": ">=18"
   },
   "dependencies": {
-    "@etoile-dev/client": "^0.3.0"
+    "@etoile-dev/client": "^0.5.0"
   },
   "devDependencies": {
     "@types/react": "^18.0.0",
     "typescript": "^5.0.0"
   }
-}
+}

package/dist/Search.d.ts

@@ -1,39 +0,0 @@
-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;
-    /** Debounce delay in milliseconds before triggering search (default: 100) */
-    debounceMs?: 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;
-    baseUrl?: string;
-};
-/**
- * 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, debounceMs, placeholder, className, renderResult, baseUrl, }: SearchProps) => import("react/jsx-runtime").JSX.Element;

package/dist/Search.js

@@ -1,31 +0,0 @@
-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, debounceMs, placeholder = "Search...", className, renderResult, baseUrl, }) => {
-    return (_jsxs(SearchRoot, { apiKey: apiKey, collections: collections, limit: limit, debounceMs: debounceMs, 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/SearchIcon.d.ts

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

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

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

package/dist/components/SearchInput.js

@@ -1,59 +0,0 @@
-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
- *
- * @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, ...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/SearchKbd.d.ts

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

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

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

package/dist/components/SearchResult.js

@@ -1,40 +0,0 @@
-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.
- * Accepts standard div props like onClick for custom behavior.
- *
- * @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, ...props }) => {
-    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", { ...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,38 +0,0 @@
-import * as React from "react";
-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;
-} & 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
- *
- * @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, ...props }: SearchResultThumbnailProps) => import("react/jsx-runtime").JSX.Element | null;

package/dist/components/SearchResultThumbnail.js

@@ -1,38 +0,0 @@
-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.
- * Accepts standard img props like loading and decoding.
- *
- * @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, ...props }) => {
-    const result = React.useContext(SearchResultDataContext);
-    const imageSrc = src ?? result?.metadata?.thumbnailUrl;
-    const imageAlt = alt ?? result?.title ?? "";
-    if (!imageSrc) {
-        return null;
-    }
-    return (_jsx("img", { ...props, src: imageSrc, alt: imageAlt, width: size, height: size, className: className, draggable: false }));
-};

package/dist/components/SearchResults.d.ts

@@ -1,39 +0,0 @@
-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;
-} & Omit<React.HTMLAttributes<HTMLDivElement>, "children">;
-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.
- * Accepts standard div props like onScroll and style.
- *
- * @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, ...props }: SearchResultsProps) => import("react/jsx-runtime").JSX.Element | null;