@seekora-ai/ui-sdk-core 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,449 @@
+import { ThemeConfig, Theme } from '@seekora-ai/ui-sdk-types';
+import { SearchResponse, SeekoraClient, SearchOptions } from '@seekora-ai/search-sdk';
+
+/**
+ * Field Mapping Utilities
+ *
+ * Shared utilities for extracting and mapping fields from API responses
+ */
+/**
+ * Get nested value from object using dot notation path
+ */
+declare const getNestedValue: (obj: any, path: string) => any;
+/**
+ * Format price value with currency
+ */
+declare const formatPrice: (value: any, currency?: string) => string | undefined;
+/**
+ * Extract field value using dot notation path
+ */
+declare const extractField: (item: any, path: string | undefined) => any;
+
+/**
+ * Theme Management Utilities
+ *
+ * Shared theme utilities for creating and merging themes
+ */
+
+/**
+ * Create a complete theme from a partial theme configuration
+ */
+declare const createTheme: (config: ThemeConfig, baseTheme: Theme) => Theme;
+/**
+ * Merge multiple themes together
+ */
+declare const mergeThemes: (baseTheme: Theme, ...themes: Partial<Theme>[]) => Theme;
+
+/**
+ * CSS Variables Theme System
+ *
+ * Generates CSS variables from theme configuration
+ * Provides utilities for injecting and managing CSS themes
+ */
+
+interface CSSVariablesConfig {
+    /** CSS selector for the theme scope (default: ':root') */
+    scope?: string;
+    /** Prefix for CSS variable names (default: '--seekora') */
+    prefix?: string;
+    /** Whether to include component classes (default: true) */
+    includeClasses?: boolean;
+}
+/**
+ * Convert a theme object to CSS variables
+ */
+declare function themeToCSSVariables(theme: Theme, config?: CSSVariablesConfig): string;
+/**
+ * Generate complete CSS stylesheet with variables and optional component classes
+ */
+declare function generateThemeStylesheet(theme: Theme, config?: CSSVariablesConfig): string;
+/**
+ * Theme presets
+ */
+declare const lightThemeVariables = "\n:root, [data-seekora-theme=\"light\"] {\n  --seekora-color-primary: #0066cc;\n  --seekora-color-secondary: #6c757d;\n  --seekora-color-background: #ffffff;\n  --seekora-color-surface: #f8f9fa;\n  --seekora-color-text: #212529;\n  --seekora-color-textSecondary: #6c757d;\n  --seekora-color-border: #dee2e6;\n  --seekora-color-hover: #f1f3f5;\n  --seekora-color-focus: rgba(0, 102, 204, 0.25);\n  --seekora-color-error: #dc3545;\n  --seekora-color-success: #28a745;\n  --seekora-color-warning: #ffc107;\n  \n  --seekora-font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, sans-serif;\n  --seekora-font-size-small: 0.875rem;\n  --seekora-font-size-medium: 1rem;\n  --seekora-font-size-large: 1.25rem;\n  --seekora-font-weight-normal: 400;\n  --seekora-font-weight-medium: 500;\n  --seekora-font-weight-semibold: 600;\n  --seekora-font-weight-bold: 700;\n  --seekora-line-height-tight: 1.25;\n  --seekora-line-height-normal: 1.5;\n  --seekora-line-height-relaxed: 1.75;\n  \n  --seekora-spacing-small: 0.5rem;\n  --seekora-spacing-medium: 1rem;\n  --seekora-spacing-large: 1.5rem;\n  \n  --seekora-border-radius: 4px;\n  --seekora-border-radius-none: 0;\n  --seekora-border-radius-small: 2px;\n  --seekora-border-radius-medium: 4px;\n  --seekora-border-radius-large: 8px;\n  --seekora-border-radius-full: 9999px;\n  \n  --seekora-shadow-small: 0 1px 2px rgba(0, 0, 0, 0.05);\n  --seekora-shadow-medium: 0 4px 6px rgba(0, 0, 0, 0.1);\n  --seekora-shadow-large: 0 10px 15px rgba(0, 0, 0, 0.1);\n  \n  --seekora-transition-fast: 150ms ease-in-out;\n  --seekora-transition-normal: 300ms ease-in-out;\n  --seekora-transition-slow: 500ms ease-in-out;\n  \n  --seekora-z-index-dropdown: 1000;\n  --seekora-z-index-modal: 1050;\n  --seekora-z-index-tooltip: 1100;\n}\n";
+declare const darkThemeVariables = "\n[data-seekora-theme=\"dark\"] {\n  --seekora-color-primary: #4da6ff;\n  --seekora-color-secondary: #adb5bd;\n  --seekora-color-background: #1a1a1a;\n  --seekora-color-surface: #2d2d2d;\n  --seekora-color-text: #f8f9fa;\n  --seekora-color-textSecondary: #adb5bd;\n  --seekora-color-border: #495057;\n  --seekora-color-hover: #343a40;\n  --seekora-color-focus: rgba(77, 166, 255, 0.25);\n  --seekora-color-error: #f87171;\n  --seekora-color-success: #4ade80;\n  --seekora-color-warning: #fbbf24;\n  \n  --seekora-shadow-small: 0 1px 2px rgba(0, 0, 0, 0.3);\n  --seekora-shadow-medium: 0 4px 6px rgba(0, 0, 0, 0.4);\n  --seekora-shadow-large: 0 10px 15px rgba(0, 0, 0, 0.5);\n}\n";
+declare const minimalThemeVariables = "\n[data-seekora-theme=\"minimal\"] {\n  --seekora-color-primary: #000000;\n  --seekora-color-secondary: #666666;\n  --seekora-color-background: #ffffff;\n  --seekora-color-surface: #fafafa;\n  --seekora-color-text: #000000;\n  --seekora-color-textSecondary: #666666;\n  --seekora-color-border: #e5e5e5;\n  --seekora-color-hover: #f5f5f5;\n  --seekora-color-focus: rgba(0, 0, 0, 0.1);\n  \n  --seekora-border-radius: 0;\n  --seekora-border-radius-none: 0;\n  --seekora-border-radius-small: 0;\n  --seekora-border-radius-medium: 0;\n  --seekora-border-radius-large: 0;\n  --seekora-border-radius-full: 0;\n  \n  --seekora-shadow-small: none;\n  --seekora-shadow-medium: none;\n  --seekora-shadow-large: none;\n}\n";
+declare const highContrastThemeVariables = "\n[data-seekora-theme=\"high-contrast\"] {\n  --seekora-color-primary: #0000ff;\n  --seekora-color-secondary: #000000;\n  --seekora-color-background: #ffffff;\n  --seekora-color-surface: #ffffff;\n  --seekora-color-text: #000000;\n  --seekora-color-textSecondary: #000000;\n  --seekora-color-border: #000000;\n  --seekora-color-hover: #ffff00;\n  --seekora-color-focus: #0000ff;\n  --seekora-color-error: #ff0000;\n  --seekora-color-success: #008000;\n  --seekora-color-warning: #ffff00;\n  \n  --seekora-font-weight-normal: 500;\n  --seekora-font-weight-medium: 600;\n  --seekora-font-weight-semibold: 700;\n  --seekora-font-weight-bold: 900;\n}\n";
+/**
+ * Complete stylesheet with all presets and component classes
+ */
+declare function generateCompleteStylesheet(): string;
+/**
+ * Inject styles into the document head
+ */
+declare function injectStyles(css: string, id?: string): void;
+/**
+ * Set the active theme
+ */
+declare function setTheme(themeName: 'light' | 'dark' | 'minimal' | 'high-contrast'): void;
+/**
+ * Get the current theme
+ */
+declare function getTheme(): string;
+
+/**
+ * Logger utility for Seekora UI SDK
+ *
+ * Provides structured logging with different log levels:
+ * - verbose: Detailed debugging information
+ * - info: General informational messages
+ * - warn: Warning messages for potential issues
+ * - error: Error messages for failures
+ */
+declare enum LogLevel {
+    VERBOSE = 0,
+    INFO = 1,
+    WARN = 2,
+    ERROR = 3,
+    SILENT = 4
+}
+interface LoggerConfig {
+    level?: LogLevel;
+    prefix?: string;
+    enableTimestamp?: boolean;
+}
+declare class Logger {
+    private level;
+    private prefix;
+    private enableTimestamp;
+    constructor(config?: LoggerConfig);
+    private getDefaultLevel;
+    private formatMessage;
+    verbose(...args: any[]): void;
+    info(...args: any[]): void;
+    warn(...args: any[]): void;
+    error(...args: any[]): void;
+    setLevel(level: LogLevel): void;
+    getLevel(): LogLevel;
+    setPrefix(prefix: string): void;
+    setTimestamp(enabled: boolean): void;
+}
+declare function createLogger(config?: LoggerConfig): Logger;
+declare function getLogger(): Logger;
+declare function setDefaultLogger(logger: Logger): void;
+declare function setLogLevel(level: LogLevel): void;
+declare function setLogPrefix(prefix: string): void;
+declare function setLogTimestamp(enabled: boolean): void;
+declare const log: {
+    verbose: (...args: any[]) => void;
+    info: (...args: any[]) => void;
+    warn: (...args: any[]) => void;
+    error: (...args: any[]) => void;
+};
+
+/**
+ * Highlight Utilities
+ *
+ * Core utilities for highlighting matching terms in search results
+ * Framework-agnostic functions shared across all packages
+ */
+interface HighlightOptions {
+    /** The attribute to highlight */
+    attribute: string;
+    /** The search hit containing highlight data */
+    hit: Record<string, any>;
+    /** Pre-tag for highlighted text (default: '<mark>') */
+    preTag?: string;
+    /** Post-tag for highlighted text (default: '</mark>') */
+    postTag?: string;
+    /** Fallback value if no highlight exists */
+    fallback?: string;
+}
+interface SnippetOptions extends HighlightOptions {
+    /** Maximum length of snippet (default: 100) */
+    maxLength?: number;
+    /** Ellipsis to use when truncating (default: '...') */
+    ellipsis?: string;
+}
+interface HighlightPart {
+    value: string;
+    isHighlighted: boolean;
+}
+/**
+ * Get highlighted value from a hit
+ * Looks for _highlightResult or highlight_result field
+ */
+declare function getHighlightedValue(options: HighlightOptions): string;
+/**
+ * Get snippet (truncated highlighted value) from a hit
+ */
+declare function getSnippetedValue(options: SnippetOptions): string;
+/**
+ * Parse highlighted value into parts for custom rendering
+ */
+declare function parseHighlightedParts(highlightedValue: string, preTag?: string, postTag?: string): HighlightPart[];
+/**
+ * Highlight a query in text (client-side highlighting)
+ * Useful when server doesn't provide highlight data
+ */
+declare function highlightQuery(text: string, query: string, options?: {
+    preTag?: string;
+    postTag?: string;
+    caseSensitive?: boolean;
+}): string;
+/**
+ * Parse query-highlighted text into parts
+ */
+declare function parseQueryHighlightParts(text: string, query: string, caseSensitive?: boolean): HighlightPart[];
+/**
+ * Strip HTML tags from highlighted text
+ */
+declare function stripHighlightTags(text: string): string;
+
+/**
+ * Accessibility Utilities
+ *
+ * Shared accessibility helpers for keyboard navigation, focus management,
+ * screen reader announcements, and ARIA attributes.
+ */
+/**
+ * Announce a message to screen readers
+ */
+declare function announce(message: string, priority?: 'polite' | 'assertive'): void;
+/**
+ * Announce search results count
+ */
+declare function announceResults(count: number, query?: string): void;
+/**
+ * Announce filter changes
+ */
+declare function announceFilterChange(action: 'added' | 'removed' | 'cleared', filterName?: string, filterValue?: string): void;
+interface KeyboardNavigationOptions {
+    /** List of navigable items */
+    items: HTMLElement[];
+    /** Current active index (-1 for none) */
+    activeIndex: number;
+    /** Callback when active index changes */
+    onActiveChange: (index: number) => void;
+    /** Callback when item is selected */
+    onSelect?: (index: number) => void;
+    /** Callback when navigation is cancelled (Escape) */
+    onCancel?: () => void;
+    /** Whether navigation wraps around */
+    wrap?: boolean;
+    /** Orientation */
+    orientation?: 'vertical' | 'horizontal' | 'both';
+}
+/**
+ * Handle keyboard navigation for a list of items
+ */
+declare function handleKeyboardNavigation(event: KeyboardEvent, options: KeyboardNavigationOptions): boolean;
+/**
+ * Create a roving tabindex manager for accessible list navigation
+ */
+declare function createRovingTabIndex(container: HTMLElement, selector: string): {
+    update: (activeIndex: number) => void;
+    destroy: () => void;
+};
+/**
+ * Get all focusable elements within a container
+ */
+declare function getFocusableElements(container: HTMLElement): HTMLElement[];
+/**
+ * Create a focus trap within a container (for modals/dialogs)
+ */
+declare function createFocusTrap(container: HTMLElement): {
+    activate: () => void;
+    deactivate: () => void;
+};
+/**
+ * Focus first error or first input in a form
+ */
+declare function focusFirstError(container: HTMLElement): boolean;
+declare function generateId(prefix?: string): string;
+/**
+ * Set up ARIA describedby relationship
+ */
+declare function setAriaDescribedBy(element: HTMLElement, describer: HTMLElement): () => void;
+/**
+ * Check if user prefers reduced motion
+ */
+declare function prefersReducedMotion(): boolean;
+/**
+ * Check if user prefers high contrast
+ */
+declare function prefersHighContrast(): boolean;
+interface KeyboardShortcut {
+    key: string;
+    ctrl?: boolean;
+    alt?: boolean;
+    shift?: boolean;
+    meta?: boolean;
+    handler: (e: KeyboardEvent) => void;
+    description?: string;
+}
+/**
+ * Create a keyboard shortcuts manager
+ */
+declare function createKeyboardShortcuts(shortcuts: KeyboardShortcut[]): {
+    attach: () => void;
+    detach: () => void;
+    getShortcuts: () => KeyboardShortcut[];
+};
+
+/**
+ * SearchStateManager
+ *
+ * Centralized state management for search operations
+ * Framework-agnostic core logic shared across all packages
+ * Handles query, refinements, pagination, sorting, and automatic search triggering
+ * Similar to InstantSearch.js architecture
+ */
+
+interface Refinement {
+    field: string;
+    value: string;
+}
+interface SearchState {
+    query: string;
+    refinements: Refinement[];
+    currentPage: number;
+    itemsPerPage: number;
+    sortBy?: string;
+    results: SearchResponse | null;
+    loading: boolean;
+    error: Error | null;
+}
+interface SearchStateManagerConfig {
+    client: SeekoraClient;
+    initialQuery?: string;
+    itemsPerPage?: number;
+    autoSearch?: boolean;
+    debounceMs?: number;
+    defaultSearchOptions?: Partial<SearchOptions>;
+}
+declare class SearchStateManager {
+    private client;
+    private state;
+    private listeners;
+    private debounceTimer;
+    private autoSearch;
+    private debounceMs;
+    private defaultSearchOptions;
+    constructor(config: SearchStateManagerConfig);
+    getState(): SearchState;
+    getQuery(): string;
+    getRefinements(): Refinement[];
+    getCurrentPage(): number;
+    getResults(): SearchResponse | null;
+    getLoading(): boolean;
+    getError(): Error | null;
+    setQuery(query: string, triggerSearch?: boolean): void;
+    addRefinement(field: string, value: string, triggerSearch?: boolean): void;
+    removeRefinement(field: string, value: string, triggerSearch?: boolean): void;
+    clearRefinements(triggerSearch?: boolean): void;
+    setPage(page: number, triggerSearch?: boolean): void;
+    setSortBy(sortBy: string, triggerSearch?: boolean): void;
+    setItemsPerPage(itemsPerPage: number, triggerSearch?: boolean): void;
+    search(additionalOptions?: Partial<SearchOptions>): Promise<SearchResponse | null>;
+    private buildSearchOptions;
+    private debouncedSearch;
+    subscribe(listener: (state: SearchState) => void): () => void;
+    private setState;
+    private notifyListeners;
+    clear(): void;
+}
+
+/**
+ * URL Router
+ *
+ * Syncs search state with browser URL for shareable links and back/forward navigation
+ * Framework-agnostic core logic shared across all packages
+ */
+
+interface URLStateMapping {
+    /** Query parameter name for search query (default: 'q') */
+    query?: string;
+    /** Query parameter name for page (default: 'page') */
+    page?: string;
+    /** Query parameter name for items per page (default: 'hitsPerPage') */
+    hitsPerPage?: string;
+    /** Query parameter name for sort (default: 'sortBy') */
+    sortBy?: string;
+    /** Prefix for refinement parameters (default: '') */
+    refinementPrefix?: string;
+    /** Custom serialization for refinements */
+    refinementSerializer?: (refinements: Refinement[]) => Record<string, string>;
+    /** Custom deserialization for refinements */
+    refinementDeserializer?: (params: URLSearchParams) => Refinement[];
+}
+interface URLRouterConfig {
+    /** SearchStateManager instance to sync with */
+    stateManager: SearchStateManager;
+    /** State mapping configuration */
+    mapping?: URLStateMapping;
+    /** Whether to write state to URL (default: true) */
+    writeToUrl?: boolean;
+    /** Whether to read initial state from URL (default: true) */
+    readFromUrl?: boolean;
+    /** Whether to use history.pushState or replaceState (default: 'push') */
+    historyMode?: 'push' | 'replace';
+    /** Debounce delay for URL updates in ms (default: 400) */
+    debounceMs?: number;
+    /** Base URL path (default: current path) */
+    basePath?: string;
+    /** Whether to trigger search on URL change (default: true) */
+    triggerSearchOnChange?: boolean;
+}
+declare class URLRouter {
+    private stateManager;
+    private mapping;
+    private writeToUrl;
+    private readFromUrl;
+    private historyMode;
+    private debounceMs;
+    private basePath;
+    private triggerSearchOnChange;
+    private unsubscribe;
+    private debounceTimer;
+    private isUpdatingFromUrl;
+    constructor(config: URLRouterConfig);
+    private init;
+    /**
+     * Read state from current URL and update StateManager
+     */
+    private readStateFromUrl;
+    /**
+     * Write state to URL
+     */
+    private writeStateToUrl;
+    /**
+     * Debounced write to URL
+     */
+    private debouncedWriteToUrl;
+    /**
+     * Handle browser back/forward navigation
+     */
+    private handlePopState;
+    /**
+     * Serialize refinements to URL params
+     */
+    private serializeRefinements;
+    /**
+     * Deserialize refinements from URL params
+     */
+    private deserializeRefinements;
+    /**
+     * Manually update URL from current state
+     */
+    refresh(): void;
+    /**
+     * Get current URL
+     */
+    getUrl(): string;
+    /**
+     * Generate shareable URL from state
+     */
+    createUrl(state?: Partial<SearchState>): string;
+    /**
+     * Destroy the router and cleanup
+     */
+    destroy(): void;
+}
+/**
+ * Create a URL router instance
+ */
+declare function createURLRouter(config: URLRouterConfig): URLRouter;
+
+export { LogLevel, SearchStateManager, URLRouter, announce, announceFilterChange, announceResults, createFocusTrap, createKeyboardShortcuts, createLogger, createRovingTabIndex, createTheme, createURLRouter, darkThemeVariables, extractField, focusFirstError, formatPrice, generateCompleteStylesheet, generateId, generateThemeStylesheet, getFocusableElements, getHighlightedValue, getLogger, getNestedValue, getSnippetedValue, getTheme, handleKeyboardNavigation, highContrastThemeVariables, highlightQuery, injectStyles, lightThemeVariables, log, mergeThemes, minimalThemeVariables, parseHighlightedParts, parseQueryHighlightParts, prefersHighContrast, prefersReducedMotion, setAriaDescribedBy, setDefaultLogger, setLogLevel, setLogPrefix, setLogTimestamp, setTheme, stripHighlightTags, themeToCSSVariables };
+export type { CSSVariablesConfig, HighlightOptions, HighlightPart, KeyboardNavigationOptions, KeyboardShortcut, LoggerConfig, Refinement, SearchState, SearchStateManagerConfig, SnippetOptions, URLRouterConfig, URLStateMapping };