@mixpeek/react-searchkit 0.1.2

package/README.md

@@ -0,0 +1,224 @@
+# @mixpeek/react-searchkit
+
+**React Components for Multimodal Search**
+
+Composable search UI with stages streaming, AI answers, filters, and theming. Free and open source.
+
+- Composable components — use the full widget or individual pieces
+- Stages streaming — watch results flow through search → rerank → enrich in real time
+- AI-generated answers with citations
+- Cmd+K keyboard shortcut
+- Light/dark theme with full customization
+- React component + CDN script tag
+
+**[Live demo: mxp.co/searchkit](https://mxp.co/searchkit)**
+
+## Install
+
+```bash
+npm install mixpeek @mixpeek/react-searchkit
+```
+
+## Quick Start
+
+### React
+
+```tsx
+import { SearchKit } from "@mixpeek/react-searchkit";
+import "@mixpeek/react-searchkit/styles.css";
+
+export default function App() {
+  return <SearchKit projectKey="your-retriever-slug" />;
+}
+```
+
+### CDN (no build step)
+
+```html
+<link rel="stylesheet" href="https://cdn.mixpeek.com/searchkit/v1/searchkit.css" />
+<script src="https://cdn.mixpeek.com/searchkit/v1/loader.js"
+  data-project-key="your-retriever-slug"
+  data-mount="search-container">
+</script>
+```
+
+## Bootstrap Your Pipeline
+
+Don't have a retriever yet? Set up a complete AI search pipeline for your site using the Mixpeek JS SDK.
+
+### 1. Scrape & Index Your Site
+
+Create a namespace, bucket, and collection with the web scraper extractor.
+
+```javascript
+import Mixpeek from "mixpeek";
+const mx = new Mixpeek({ apiKey: "YOUR_API_KEY" });
+
+// Create a namespace with web scraper + text search
+const namespace = await mx.namespaces.create({
+  namespace_name: "my-site",
+  feature_extractors: [
+    { feature_extractor_name: "web_scraper", version: "v1" },
+    { feature_extractor_name: "text_extractor", version: "v1" }
+  ]
+});
+
+// Create a bucket and upload your URLs
+const bucket = await mx.buckets.create({ bucket_name: "pages" });
+await mx.buckets.objects.create(bucket.bucket_id, {
+  blobs: [{ property: "url", type: "text", data: "https://yoursite.com" }]
+});
+
+// Create a collection to process pages
+const collection = await mx.collections.create({
+  collection_name: "site-pages",
+  source: { type: "bucket", bucket_ids: [bucket.bucket_id] },
+  feature_extractor: {
+    feature_extractor_name: "web_scraper",
+    version: "v1",
+    input_mappings: { url: "url" }
+  }
+});
+
+// Trigger processing
+await mx.collections.trigger(collection.collection_id);
+```
+
+### 2. Create a Retriever with Streaming Stages
+
+Build a multi-stage search pipeline with semantic search and reranking. Each stage streams results to the UI in real time.
+
+```javascript
+const retriever = await mx.retrievers.create({
+  retriever_name: "site-search",
+  collection_identifiers: ["site-pages"],
+  stages: [
+    {
+      stage_name: "search",
+      stage_type: "feature_search",
+      parameters: {
+        feature_uri: "mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1",
+        input_mode: "text",
+        limit: 20
+      }
+    },
+    {
+      stage_name: "rerank",
+      stage_type: "rerank",
+      parameters: { model: "mixpeek/reranker", top_k: 10 }
+    }
+  ]
+});
+
+// Publish it so the widget can access it
+await mx.retrievers.publish(retriever.retriever_id, {
+  slug: "my-site-search"
+});
+```
+
+### 3. Drop in the Widget
+
+```tsx
+import { SearchKit } from "@mixpeek/react-searchkit";
+import "@mixpeek/react-searchkit/styles.css";
+
+export default function App() {
+  return <SearchKit projectKey="my-site-search" enableAIAnswer />;
+}
+```
+
+## Composable Components
+
+Use the full `<SearchKit />` widget or import individual pieces and compose your own UI.
+
+### Context Hook
+
+Access search state from any child component:
+
+```tsx
+import { useSearchKit } from "@mixpeek/react-searchkit";
+
+function MyResults() {
+  const { query, results, isLoading, stages, open, close } = useSearchKit();
+
+  return (
+    <div>
+      {stages.map((stage) => (
+        <div key={stage.name}>
+          {stage.name}: {stage.status} ({stage.resultCount} results)
+        </div>
+      ))}
+      {results.map((result, i) => (
+        <div key={i}>{result.title}</div>
+      ))}
+    </div>
+  );
+}
+```
+
+### Custom Result Rendering
+
+```tsx
+<SearchKit
+  projectKey="my-retriever"
+  renderResult={(result, index) => (
+    <div className="my-result">
+      <h3>{result.title}</h3>
+      <p>{result.content}</p>
+    </div>
+  )}
+/>
+```
+
+### Field Mapping
+
+Use `transformResults` to map your retriever's fields to the widget format:
+
+```tsx
+<SearchKit
+  projectKey="my-retriever"
+  transformResults={(results) =>
+    results.map((r) => ({
+      ...r,
+      title: r.product_name || r.title,
+      content: r.description,
+      page_url: `/products/${r.id}`,
+    }))
+  }
+/>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `projectKey` | `string` | required | Public retriever slug or `ret_sk_` API key |
+| `placeholder` | `string` | `"Search..."` | Input placeholder text |
+| `maxResults` | `number` | `10` | Maximum results to display |
+| `theme` | `"light" \| "dark" \| "auto"` | `"auto"` | Color theme |
+| `accentColor` | `string` | `"#6366f1"` | Accent color (hex) |
+| `position` | `"modal" \| "inline"` | `"modal"` | Modal overlay or inline embed |
+| `keyboardShortcut` | `boolean` | `true` | Enable Cmd+K / Ctrl+K |
+| `showPoweredBy` | `boolean` | `true` | Show "Search by Mixpeek" badge |
+| `enableAIAnswer` | `boolean` | `false` | Show AI-generated answer panel |
+| `enableShareLinks` | `boolean` | `false` | Enable shareable search URLs |
+| `onSearch` | `(query: string) => void` | - | Callback when search is performed |
+| `onResultClick` | `(result, index) => void` | - | Callback when result is clicked |
+| `onZeroResults` | `(query: string) => void` | - | Callback when no results found |
+| `transformResults` | `(results) => results` | - | Transform results before rendering |
+| `renderResult` | `(result, index) => ReactNode` | - | Custom result renderer |
+| `retrieverSlug` | `string` | - | Retriever slug when using `ret_sk_` key |
+| `apiBaseUrl` | `string` | `"https://api.mixpeek.com"` | Custom API URL |
+| `className` | `string` | - | Additional CSS class |
+| `defaultOpen` | `boolean` | `false` | Start with modal open |
+
+## Links
+
+- [Connector page](https://mxp.co/searchkit)
+- [GitHub](https://github.com/mixpeek/searchkit)
+- [npm](https://www.npmjs.com/package/@mixpeek/react-searchkit)
+- [Docs](https://mixpeek.com/docs)
+
+## License
+
+MIT

package/dist/AIAnswer.d.ts

@@ -0,0 +1,9 @@
+import { default as React } from 'react';
+import { AIAnswerData } from './types';
+
+interface AIAnswerProps {
+    data: AIAnswerData;
+    onCitationClick?: (resultIndex: number) => void;
+}
+export declare const AIAnswer: React.FC<AIAnswerProps>;
+export {};

package/dist/IntentCTA.d.ts

@@ -0,0 +1,8 @@
+import { default as React } from 'react';
+import { CTAConfig } from './types';
+
+interface IntentCTAProps {
+    config: CTAConfig;
+}
+export declare const IntentCTA: React.FC<IntentCTAProps>;
+export {};

package/dist/PoweredBy.d.ts

@@ -0,0 +1,9 @@
+import { default as React } from 'react';
+import { ThemeMode } from './types';
+
+interface PoweredByProps {
+    /** Explicit theme override (CSS custom properties handle it by default) */
+    theme?: ThemeMode;
+}
+export declare const PoweredBy: React.FC<PoweredByProps>;
+export {};

package/dist/ResultCard.d.ts

@@ -0,0 +1,11 @@
+import { default as React } from 'react';
+import { SearchResult } from './types';
+
+interface ResultCardProps {
+    result: SearchResult;
+    index: number;
+    query: string;
+    onResultClick?: (result: SearchResult, index: number) => void;
+}
+export declare const ResultCard: React.FC<ResultCardProps>;
+export {};

package/dist/SearchButton.d.ts

@@ -0,0 +1,9 @@
+import { default as React } from 'react';
+
+interface SearchButtonProps {
+    onClick: () => void;
+    placeholder: string;
+    keyboardShortcut: boolean;
+}
+export declare const SearchButton: React.FC<SearchButtonProps>;
+export {};

package/dist/SearchInput.d.ts

@@ -0,0 +1,11 @@
+import { default as React } from 'react';
+
+interface SearchInputProps {
+    value: string;
+    onChange: (value: string) => void;
+    placeholder: string;
+    isLoading: boolean;
+    onClear: () => void;
+}
+export declare const SearchInput: React.FC<SearchInputProps>;
+export {};

package/dist/SearchKit.d.ts

@@ -0,0 +1,35 @@
+import { default as React } from 'react';
+import { SearchKitProps, SearchContextValue } from './types';
+
+/**
+ * Hook to access the SearchKit context from child components.
+ */
+export declare function useSearchKit(): SearchContextValue;
+/** @deprecated Use useSearchKit instead */
+export declare const useMixpeekSearch: typeof useSearchKit;
+/**
+ * SearchKit - React component library for multimodal search.
+ *
+ * Renders a search button that opens a search modal with stages streaming,
+ * AI answers, filters, recent searches, and theming.
+ *
+ * @example
+ * ```tsx
+ * <SearchKit projectKey="my-retriever-slug" />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <SearchKit
+ *   projectKey="ret_sk_abc123"
+ *   theme="dark"
+ *   placeholder="Search documentation..."
+ *   maxResults={20}
+ *   onResultClick={(result) => window.location.href = result.page_url}
+ * />
+ * ```
+ */
+export declare const SearchKit: React.FC<SearchKitProps>;
+/** @deprecated Use SearchKit instead */
+export declare const MixpeekSearch: React.FC<SearchKitProps>;
+export default SearchKit;

package/dist/SearchModal.d.ts

@@ -0,0 +1,28 @@
+import { default as React, ReactNode } from 'react';
+import { SearchResult, AIAnswerData, SearchResponseMetadata, CTAConfig, StageGroup } from './types';
+
+interface SearchModalProps {
+    isOpen: boolean;
+    onClose: () => void;
+    query: string;
+    onQueryChange: (query: string) => void;
+    results: SearchResult[];
+    stages: StageGroup[];
+    isStreaming: boolean;
+    isLoading: boolean;
+    error: string | null;
+    aiAnswer: AIAnswerData | null;
+    metadata: SearchResponseMetadata | null;
+    placeholder: string;
+    showPoweredBy: boolean;
+    enableShareLinks: boolean;
+    enableAIAnswer: boolean;
+    recentSearches: string[];
+    onClearRecent: () => void;
+    onResultClick?: (result: SearchResult, index: number) => void;
+    renderResult?: (result: SearchResult, index: number) => ReactNode;
+    ctaConfig?: CTAConfig;
+    theme?: string;
+}
+export declare const SearchModal: React.FC<SearchModalProps>;
+export {};

package/dist/SearchResults.d.ts

@@ -0,0 +1,14 @@
+import { default as React, ReactNode } from 'react';
+import { SearchResult, StageGroup } from './types';
+
+interface SearchResultsProps {
+    results: SearchResult[];
+    stages: StageGroup[];
+    isStreaming: boolean;
+    query: string;
+    isLoading: boolean;
+    onResultClick?: (result: SearchResult, index: number) => void;
+    renderResult?: (result: SearchResult, index: number) => ReactNode;
+}
+export declare const SearchResults: React.FC<SearchResultsProps>;
+export {};

package/dist/ShareLink.d.ts

@@ -0,0 +1,7 @@
+import { default as React } from 'react';
+
+interface ShareLinkProps {
+    query: string;
+}
+export declare const ShareLink: React.FC<ShareLinkProps>;
+export {};

package/dist/ZeroResults.d.ts

@@ -0,0 +1,7 @@
+import { default as React } from 'react';
+
+interface ZeroResultsProps {
+    query: string;
+}
+export declare const ZeroResults: React.FC<ZeroResultsProps>;
+export {};

package/dist/api/client.d.ts

@@ -0,0 +1,44 @@
+import { SearchResponse, StageEvent } from '../types';
+
+interface MixpeekClientConfig {
+    projectKey: string;
+    baseUrl?: string;
+    /** When using a ret_sk_ key, specify the public retriever slug for the endpoint URL */
+    retrieverSlug?: string;
+    /**
+     * Bearer token for private API access (local dev / self-hosted).
+     * When set, uses `Authorization: Bearer <bearerToken>` instead of the public key header,
+     * and routes directly to the private `/v1/retrievers/{id}/execute` endpoint.
+     */
+    bearerToken?: string;
+}
+interface SearchParams {
+    query: string;
+    limit?: number;
+    stream?: boolean;
+    inputs?: Record<string, unknown>;
+}
+export declare class MixpeekClient {
+    private projectKey;
+    private baseUrl;
+    private retrieverSlug;
+    private bearerToken;
+    private abortController;
+    constructor(config: MixpeekClientConfig);
+    private isApiKey;
+    private getHeaders;
+    private getEndpoint;
+    /**
+     * Cancel any in-flight search request.
+     */
+    cancel(): void;
+    /**
+     * Execute a search query against the configured retriever.
+     */
+    search(params: SearchParams): Promise<SearchResponse>;
+    /**
+     * Execute a streaming search query. Yields StageEvent objects as the pipeline executes.
+     */
+    searchStream(params: SearchParams): AsyncGenerator<StageEvent>;
+}
+export {};

package/dist/filters/FacetFilter.d.ts

@@ -0,0 +1,10 @@
+import { default as React } from 'react';
+import { FacetFilterConfig } from '../types';
+
+interface FacetFilterProps {
+    config: FacetFilterConfig;
+    value: unknown;
+    onChange: (field: string, value: unknown) => void;
+}
+export declare const FacetFilter: React.FC<FacetFilterProps>;
+export {};

package/dist/filters/FilterPanel.d.ts

@@ -0,0 +1,12 @@
+import { default as React } from 'react';
+import { FilterPanelConfig } from '../types';
+
+interface FilterPanelProps {
+    config: FilterPanelConfig;
+    filterInputs: Record<string, unknown>;
+    onFilterChange: (field: string, value: unknown) => void;
+    onClearAll?: () => void;
+    hasActiveFilters?: boolean;
+}
+export declare const FilterPanel: React.FC<FilterPanelProps>;
+export {};

package/dist/filters/RangeFilter.d.ts

@@ -0,0 +1,11 @@
+import { default as React } from 'react';
+import { RangeFilterConfig } from '../types';
+
+interface RangeFilterProps {
+    config: RangeFilterConfig;
+    minValue?: number;
+    maxValue?: number;
+    onChange: (field: string, value: unknown) => void;
+}
+export declare const RangeFilter: React.FC<RangeFilterProps>;
+export {};

package/dist/filters/SmartFilter.d.ts

@@ -0,0 +1,10 @@
+import { default as React } from 'react';
+import { SmartFilterConfig } from '../types';
+
+interface SmartFilterProps {
+    config: SmartFilterConfig;
+    value?: string;
+    onChange: (field: string, value: unknown) => void;
+}
+export declare const SmartFilter: React.FC<SmartFilterProps>;
+export {};

package/dist/filters/index.d.ts

@@ -0,0 +1,4 @@
+export { FilterPanel } from './FilterPanel';
+export { FacetFilter } from './FacetFilter';
+export { RangeFilter } from './RangeFilter';
+export { SmartFilter } from './SmartFilter';

package/dist/hooks/useFilters.d.ts

@@ -0,0 +1,10 @@
+interface UseFiltersReturn {
+    filterInputs: Record<string, unknown>;
+    setFilter: (field: string, value: unknown) => void;
+    removeFilter: (field: string) => void;
+    clearFilters: () => void;
+    hasActiveFilters: boolean;
+    getFilter: (field: string) => unknown;
+}
+export declare function useFilters(defaultFilters?: Record<string, unknown>): UseFiltersReturn;
+export {};

package/dist/hooks/useKeyboardShortcut.d.ts

@@ -0,0 +1,12 @@
+interface UseKeyboardShortcutOptions {
+    /** Whether the shortcut is enabled */
+    enabled: boolean;
+    /** Callback when shortcut is triggered */
+    onTrigger: () => void;
+}
+/**
+ * Listens for Cmd+K (Mac) or Ctrl+K (Windows/Linux) to trigger search.
+ * Also listens for Escape to close.
+ */
+export declare function useKeyboardShortcut(options: UseKeyboardShortcutOptions): void;
+export {};

package/dist/hooks/useRecentSearches.d.ts

@@ -0,0 +1,7 @@
+interface UseRecentSearchesReturn {
+    recentSearches: string[];
+    addSearch: (query: string) => void;
+    clearRecentSearches: () => void;
+}
+export declare function useRecentSearches(): UseRecentSearchesReturn;
+export {};

package/dist/hooks/useSearch.d.ts

@@ -0,0 +1,22 @@
+import { SearchResult, AIAnswerData, SearchResponseMetadata, SearchKitConfig, StageGroup } from '../types';
+
+interface UseSearchOptions {
+    config: SearchKitConfig;
+    filterInputs?: Record<string, unknown>;
+    onSearch?: (query: string) => void;
+    onSearchExecuted?: (query: string) => void;
+    onZeroResults?: (query: string) => void;
+    transformResults?: (results: SearchResult[]) => SearchResult[];
+}
+interface UseSearchReturn {
+    results: SearchResult[];
+    stages: StageGroup[];
+    isLoading: boolean;
+    isStreaming: boolean;
+    error: string | null;
+    aiAnswer: AIAnswerData | null;
+    metadata: SearchResponseMetadata | null;
+    search: (query: string) => Promise<void>;
+}
+export declare function useSearch(options: UseSearchOptions): UseSearchReturn;
+export {};

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @mixpeek/react-searchkit - React component library for multimodal search.
+ *
+ * Composable search UI with stages streaming, AI answers, filters, and theming.
+ *
+ * @example React usage:
+ * ```tsx
+ * import { SearchKit } from "@mixpeek/react-searchkit";
+ * import "@mixpeek/react-searchkit/styles.css";
+ *
+ * function App() {
+ *   return <SearchKit projectKey="my-retriever-slug" />;
+ * }
+ * ```
+ *
+ * @example CDN usage:
+ * ```html
+ * <script src="https://cdn.mixpeek.com/searchkit/v1/searchkit.umd.js"></script>
+ * <div id="mixpeek-search" data-project-key="my-retriever-slug"></div>
+ * ```
+ */
+export { SearchKit, MixpeekSearch, useSearchKit, useMixpeekSearch } from './SearchKit';
+export { SearchButton } from './SearchButton';
+export { SearchModal } from './SearchModal';
+export { SearchInput } from './SearchInput';
+export { AIAnswer } from './AIAnswer';
+export { SearchResults } from './SearchResults';
+export { ResultCard } from './ResultCard';
+export { PoweredBy } from './PoweredBy';
+export { ShareLink } from './ShareLink';
+export { ZeroResults } from './ZeroResults';
+export { IntentCTA } from './IntentCTA';
+export { FilterPanel, FacetFilter, RangeFilter, SmartFilter } from './filters';
+export { useSearch } from './hooks/useSearch';
+export { useFilters } from './hooks/useFilters';
+export { useKeyboardShortcut } from './hooks/useKeyboardShortcut';
+export { useRecentSearches } from './hooks/useRecentSearches';
+export { MixpeekClient } from './api/client';
+export type { SearchKitProps, SearchKitProps as MixpeekSearchProps, SearchResult, AIAnswerData, AIAnswerCitation, SearchResponse, SearchResponseMetadata, CTAConfig, SearchContextValue, SearchKitConfig, SearchKitConfig as MixpeekSearchConfig, ThemeMode, Position, RecentSearch, StageEvent, StageStatistics, StageGroup, FacetOption, FacetFilterConfig, RangeFilterConfig, SmartFilterConfig, FilterConfig, FilterPanelConfig, } from './types';