@seekora-ai/docsearch-react 0.1.1

package/README.md

@@ -0,0 +1,108 @@
+# @seekora/docsearch-react
+
+React component for Seekora DocSearch - documentation search modal with keyboard navigation.
+
+## Installation
+
+```bash
+npm install @seekora/docsearch-react @seekora/docsearch-css
+```
+
+## Usage
+
+```tsx
+import { DocSearch } from '@seekora/docsearch-react';
+import '@seekora/docsearch-css';
+
+function App() {
+  return (
+    <DocSearch
+      apiEndpoint="https://api.example.com/v1/docs"
+      placeholder="Search documentation..."
+      onSelect={(hit) => {
+        // Custom navigation logic
+        window.location.href = hit.url;
+      }}
+    />
+  );
+}
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `apiEndpoint` | `string` | required | Base URL for the search API |
+| `apiKey` | `string` | - | Optional API key for authentication |
+| `indexName` | `string` | - | Optional index name |
+| `placeholder` | `string` | "Search documentation..." | Input placeholder |
+| `maxResults` | `number` | 10 | Maximum results |
+| `debounceMs` | `number` | 200 | Debounce delay |
+| `onSelect` | `(hit) => void` | - | Selection callback |
+| `onClose` | `() => void` | - | Modal close callback |
+| `translations` | `object` | - | Custom UI text |
+| `renderButton` | `boolean` | true | Show trigger button |
+| `initialOpen` | `boolean` | false | Start with modal open |
+| `disableShortcut` | `boolean` | false | Disable Cmd+K shortcut |
+| `shortcutKey` | `string` | "k" | Custom shortcut key |
+
+## Hooks
+
+### useDocSearch
+
+Access search state and actions programmatically:
+
+```tsx
+import { useDocSearch } from '@seekora/docsearch-react';
+
+function CustomSearch() {
+  const {
+    query,
+    setQuery,
+    suggestions,
+    isLoading,
+    selectedIndex,
+    selectNext,
+    selectPrev,
+  } = useDocSearch({
+    apiEndpoint: 'https://api.example.com/v1/docs',
+  });
+
+  return (
+    <input
+      value={query}
+      onChange={(e) => setQuery(e.target.value)}
+      onKeyDown={(e) => {
+        if (e.key === 'ArrowDown') selectNext();
+        if (e.key === 'ArrowUp') selectPrev();
+      }}
+    />
+  );
+}
+```
+
+### useKeyboard
+
+Handle keyboard shortcuts:
+
+```tsx
+import { useKeyboard, getShortcutText } from '@seekora/docsearch-react';
+
+function MyComponent() {
+  const { handleModalKeyDown } = useKeyboard({
+    isOpen,
+    onOpen: () => setIsOpen(true),
+    onClose: () => setIsOpen(false),
+    onSelectNext: () => {},
+    onSelectPrev: () => {},
+    onEnter: () => {},
+  });
+
+  // getShortcutText returns "⌘K" on Mac, "Ctrl+K" on Windows
+  console.log(getShortcutText('K'));
+}
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,395 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React$1 from 'react';
+
+/**
+ * Seekora DocSearch Types
+ */
+interface DocSearchHit {
+    objectID: string;
+    url: string;
+    anchor?: string;
+    title: string;
+    content: string;
+    section_level: number;
+    hierarchy: {
+        lvl0?: string;
+        lvl1?: string;
+        lvl2?: string;
+        lvl3?: string;
+        lvl4?: string;
+        lvl5?: string;
+    };
+    _highlightResult?: {
+        title?: {
+            value: string;
+            matchLevel: string;
+        };
+        content?: {
+            value: string;
+            matchLevel: string;
+        };
+        hierarchy?: {
+            lvl0?: {
+                value: string;
+                matchLevel: string;
+            };
+            lvl1?: {
+                value: string;
+                matchLevel: string;
+            };
+            lvl2?: {
+                value: string;
+                matchLevel: string;
+            };
+            lvl3?: {
+                value: string;
+                matchLevel: string;
+            };
+        };
+    };
+    _source?: string;
+}
+interface DocSearchSuggestion {
+    url: string;
+    title: string;
+    content?: string;
+    description?: string;
+    category?: string;
+    hierarchy?: {
+        lvl0?: string;
+        lvl1?: string;
+        lvl2?: string;
+        lvl3?: string;
+        lvl4?: string;
+        lvl5?: string;
+    };
+    highlight?: {
+        title?: string;
+        content?: string;
+    };
+    _source?: string;
+    route?: string;
+    parentTitle?: string;
+    type?: string;
+    anchor?: string;
+}
+/**
+ * Search source configuration for multi-source search
+ */
+interface SearchSource {
+    /** Unique identifier for this source */
+    id: string;
+    /** Display name for the source (e.g., "Pages", "Documentation") */
+    name: string;
+    /** API endpoint for this source */
+    endpoint: string;
+    /** Optional API key for this source */
+    apiKey?: string;
+    /** Maximum results from this source */
+    maxResults?: number;
+    /** Minimum query length to trigger search for this source */
+    minQueryLength?: number;
+    /** Transform function to normalize results */
+    transformResults?: (data: any) => DocSearchSuggestion[];
+    /** Whether to open links in new tab */
+    openInNewTab?: boolean;
+    /** Icon for this source (optional) */
+    icon?: string;
+}
+interface DocSearchResponse {
+    hits: DocSearchHit[];
+    query: string;
+    total?: number;
+    page?: number;
+    nbPages?: number;
+}
+interface DocSearchSuggestionsResponse {
+    suggestions: DocSearchSuggestion[];
+    query: string;
+}
+interface DocSearchProps {
+    /**
+     * Seekora Store ID for search
+     * When provided, uses the Seekora SDK for searching
+     */
+    storeId?: string;
+    /**
+     * Seekora Store Secret for authentication
+     * Optional for public stores
+     */
+    storeSecret?: string;
+    /**
+     * Seekora API endpoint override
+     * Defaults to production (https://api.seekora.com/api)
+     * Can be 'local', 'stage', 'production', or a custom URL
+     */
+    seekoraApiEndpoint?: string;
+    /**
+     * @deprecated Use storeId and storeSecret instead
+     * Legacy API endpoint for search (e.g., "https://api.example.com/v1/docs") - used if sources not provided
+     */
+    apiEndpoint?: string;
+    /**
+     * @deprecated Use storeId and storeSecret instead
+     * Optional API key for authentication - used if sources not provided
+     */
+    apiKey?: string;
+    /** Multiple search sources for unified search */
+    sources?: SearchSource[];
+    /** Index name (optional, some APIs may not need this) */
+    indexName?: string;
+    /** Placeholder text for the search input */
+    placeholder?: string;
+    /** Maximum number of results to show */
+    maxResults?: number;
+    /** Debounce delay in milliseconds */
+    debounceMs?: number;
+    /** Callback when a result is selected */
+    onSelect?: (hit: DocSearchHit | DocSearchSuggestion) => void;
+    /** Callback when the modal is closed */
+    onClose?: () => void;
+    /** Custom translations */
+    translations?: DocSearchTranslations;
+    /** Whether to render the button trigger */
+    renderButton?: boolean;
+    /** Custom button component */
+    buttonComponent?: React.ComponentType<DocSearchButtonProps>;
+    /** Initial open state */
+    initialOpen?: boolean;
+    /** Disable keyboard shortcut */
+    disableShortcut?: boolean;
+    /** Custom keyboard shortcut key (default: 'k') */
+    shortcutKey?: string;
+}
+interface DocSearchButtonProps {
+    onClick: () => void;
+    placeholder?: string;
+}
+interface DocSearchTranslations {
+    buttonText?: string;
+    buttonAriaLabel?: string;
+    searchPlaceholder?: string;
+    noResultsText?: string;
+    loadingText?: string;
+    errorText?: string;
+    footerText?: string;
+    closeText?: string;
+    searchByText?: string;
+}
+interface DocSearchState {
+    query: string;
+    results: DocSearchHit[];
+    suggestions: DocSearchSuggestion[];
+    isLoading: boolean;
+    error: string | null;
+    selectedIndex: number;
+    mode: 'suggestions' | 'results';
+}
+type DocSearchAction = {
+    type: 'SET_QUERY';
+    payload: string;
+} | {
+    type: 'SET_RESULTS';
+    payload: DocSearchHit[];
+} | {
+    type: 'SET_SUGGESTIONS';
+    payload: DocSearchSuggestion[];
+} | {
+    type: 'SET_LOADING';
+    payload: boolean;
+} | {
+    type: 'SET_ERROR';
+    payload: string | null;
+} | {
+    type: 'SET_SELECTED_INDEX';
+    payload: number;
+} | {
+    type: 'SELECT_NEXT';
+} | {
+    type: 'SELECT_PREV';
+} | {
+    type: 'SET_MODE';
+    payload: 'suggestions' | 'results';
+} | {
+    type: 'RESET';
+};
+
+declare function DocSearch({ storeId, storeSecret, seekoraApiEndpoint, apiEndpoint, apiKey, sources, placeholder, maxResults, debounceMs, onSelect, onClose, translations, renderButton, buttonComponent: ButtonComponent, initialOpen, disableShortcut, shortcutKey, }: DocSearchProps): react_jsx_runtime.JSX.Element;
+
+declare function DocSearchButton({ onClick, placeholder, }: DocSearchButtonProps): react_jsx_runtime.JSX.Element;
+
+interface ModalProps {
+    isOpen: boolean;
+    onClose: () => void;
+    children: React$1.ReactNode;
+}
+/**
+ * Modal component that renders via React Portal to document.body.
+ * This ensures the search overlay renders independently of its integration context,
+ * avoiding clipping/positioning issues from parent overflow, transform, or stacking contexts.
+ */
+declare function Modal({ isOpen, onClose, children }: ModalProps): React$1.ReactPortal | null;
+
+interface SearchBoxProps {
+    value: string;
+    onChange: (value: string) => void;
+    onKeyDown: (event: React$1.KeyboardEvent) => void;
+    placeholder?: string;
+    isLoading?: boolean;
+    onClear?: () => void;
+}
+declare function SearchBox({ value, onChange, onKeyDown, placeholder, isLoading, onClear, }: SearchBoxProps): react_jsx_runtime.JSX.Element;
+
+interface GroupedHits {
+    source: SearchSource;
+    items: DocSearchSuggestion[];
+}
+interface ResultsProps {
+    hits: (DocSearchHit | DocSearchSuggestion)[];
+    groupedHits?: GroupedHits[];
+    selectedIndex: number;
+    onSelect: (hit: DocSearchHit | DocSearchSuggestion) => void;
+    onHover: (index: number) => void;
+    query: string;
+    isLoading: boolean;
+    error: string | null;
+    translations?: DocSearchTranslations;
+    sources?: SearchSource[];
+}
+declare function Results({ hits, groupedHits, selectedIndex, onSelect, onHover, query, isLoading, error, translations, sources: _sources, }: ResultsProps): react_jsx_runtime.JSX.Element;
+
+interface HitProps {
+    hit: DocSearchHit | DocSearchSuggestion;
+    isSelected: boolean;
+    onClick: () => void;
+    onMouseEnter: () => void;
+    openInNewTab?: boolean;
+    isChild?: boolean;
+    isLastChild?: boolean;
+    /** Hierarchy type from API (lvl1, lvl2, lvl3, etc.) - source of truth for icon and display */
+    hierarchyType?: string;
+}
+declare function Hit({ hit, isSelected, onClick, onMouseEnter, openInNewTab, isChild, isLastChild, hierarchyType }: HitProps): react_jsx_runtime.JSX.Element;
+
+interface HighlightProps {
+    value: string;
+    highlightedValue?: string;
+}
+/**
+ * Renders text with highlighted matches.
+ * Expects highlightedValue to contain <mark> tags around matches.
+ */
+declare function Highlight({ value, highlightedValue }: HighlightProps): react_jsx_runtime.JSX.Element;
+/**
+ * Truncate content and highlight the matched portion.
+ */
+declare function truncateAroundMatch(content: string, maxLength?: number): string;
+
+interface FooterProps {
+    translations?: DocSearchTranslations;
+}
+declare function Footer({ translations }: FooterProps): react_jsx_runtime.JSX.Element;
+
+interface UseDocSearchOptions {
+    /** Single API endpoint (legacy mode) */
+    apiEndpoint?: string;
+    /** Single API key (legacy mode) */
+    apiKey?: string;
+    /** Multiple search sources */
+    sources?: SearchSource[];
+    maxResults?: number;
+    debounceMs?: number;
+}
+declare function useDocSearch(options: UseDocSearchOptions): {
+    sources: SearchSource[];
+    setQuery: (query: string) => void;
+    search: (query: string) => Promise<void>;
+    fetchSuggestions: (query: string) => Promise<void>;
+    selectNext: () => void;
+    selectPrev: () => void;
+    setSelectedIndex: (index: number) => void;
+    reset: () => void;
+    getSelectedItem: () => DocSearchHit | DocSearchSuggestion | null;
+    groupedSuggestions: {
+        source: SearchSource;
+        items: DocSearchSuggestion[];
+    }[];
+    query: string;
+    results: DocSearchHit[];
+    suggestions: DocSearchSuggestion[];
+    isLoading: boolean;
+    error: string | null;
+    selectedIndex: number;
+    mode: "suggestions" | "results";
+};
+
+interface UseSeekoraSearchOptions {
+    /** Seekora Store ID */
+    storeId: string;
+    /** Seekora Store Secret (optional for public stores) */
+    storeSecret?: string;
+    /** API endpoint override - can be 'local', 'stage', 'production', or a custom URL */
+    apiEndpoint?: string;
+    /** Maximum results to return */
+    maxResults?: number;
+    /** Debounce delay in milliseconds */
+    debounceMs?: number;
+    /** Analytics tags to include with searches */
+    analyticsTags?: string[];
+    /** Group results by this field (e.g., 'hierarchy.lvl0' for doc search) */
+    groupField?: string;
+    /** Number of results per group */
+    groupSize?: number;
+}
+interface UseSeekoraSearchResult {
+    /** Current query */
+    query: string;
+    /** Search suggestions/results */
+    suggestions: DocSearchSuggestion[];
+    /** Whether a search is in progress */
+    isLoading: boolean;
+    /** Error message if any */
+    error: string | null;
+    /** Currently selected index for keyboard navigation */
+    selectedIndex: number;
+    /** Set the query and trigger search */
+    setQuery: (query: string) => void;
+    /** Select next result */
+    selectNext: () => void;
+    /** Select previous result */
+    selectPrev: () => void;
+    /** Set selected index directly */
+    setSelectedIndex: (index: number) => void;
+    /** Reset state */
+    reset: () => void;
+    /** Get currently selected item */
+    getSelectedItem: () => DocSearchSuggestion | null;
+}
+/**
+ * Hook for searching using the Seekora SDK
+ *
+ * This hook provides a seamless integration with the Seekora Search SDK,
+ * handling client initialization, debouncing, and result transformation.
+ */
+declare function useSeekoraSearch(options: UseSeekoraSearchOptions): UseSeekoraSearchResult;
+
+interface UseKeyboardOptions {
+    isOpen: boolean;
+    onOpen: () => void;
+    onClose: () => void;
+    onSelectNext: () => void;
+    onSelectPrev: () => void;
+    onEnter: () => void;
+    disableShortcut?: boolean;
+    shortcutKey?: string;
+}
+declare function useKeyboard(options: UseKeyboardOptions): {
+    handleModalKeyDown: (event: KeyboardEvent | React.KeyboardEvent) => void;
+};
+/**
+ * Get the keyboard shortcut display text based on platform
+ */
+declare function getShortcutText(key?: string): string;
+
+export { DocSearch, DocSearchButton, Footer, Highlight, Hit, Modal, Results, SearchBox, getShortcutText, truncateAroundMatch, useDocSearch, useKeyboard, useSeekoraSearch };
+export type { DocSearchAction, DocSearchButtonProps, DocSearchHit, DocSearchProps, DocSearchResponse, DocSearchState, DocSearchSuggestion, DocSearchSuggestionsResponse, DocSearchTranslations, SearchSource, UseSeekoraSearchOptions, UseSeekoraSearchResult };