import { ReactNode } from 'react';

/** A single command item in the palette */
interface CommandItem {
    /** Unique identifier */
    id: string;
    /** Display label shown in the palette */
    label: string;
    /** Optional description text */
    description?: string;
    /** Icon — string, emoji, or React element (e.g. `<Settings size={16} />`) */
    icon?: ReactNode;
    /** Additional search terms for fuzzy matching */
    keywords?: string[];
    /** Group this command belongs to */
    group?: string;
    /** Manual ordering weight (higher = appears first) */
    priority?: number;
    /** Navigation target URL/path for route commands */
    href?: string;
    /** Execution callback when command is selected */
    action?: (item: CommandItem) => void | Promise<void>;
    /** Whether this command is disabled */
    disabled?: boolean;
    /** Hidden from results but still searchable */
    hidden?: boolean;
    /** Required permissions to see this command */
    permissions?: string[];
    /** Keyboard shortcut display (e.g., ["g", "h"]) */
    shortcut?: string[];
    /** Extensible metadata for consumer use */
    meta?: Record<string, unknown>;
    /** Scopes where this command is most relevant (e.g., ['/billing', '/billing/*']) */
    scope?: string[];
    /** Child commands for nested/hierarchical menus */
    children?: CommandItem[];
    /** Parent command ID (set automatically when flattening) */
    parentId?: string;
}
/** A search engine implementation */
interface SearchEngine {
    /** Search items against a query string. Returns scored results. */
    search(query: string, items: CommandItem[]): ScoredItem[];
}
/** A command item with a relevance score */
interface ScoredItem {
    /** The matched command item */
    item: CommandItem;
    /** Relevance score from 0 (worst) to 1 (best match) */
    score: number;
}

/**
 * Create a search engine backed by match-sorter.
 * Requires `match-sorter` as a peer dependency.
 *
 * match-sorter provides excellent ranking for "type what you remember" UX,
 * with configurable thresholds and multi-key support.
 *
 * @param options.threshold - match-sorter threshold (default: CONTAINS)
 * @param options.keys - Additional keys to search beyond defaults
 */
declare function createMatchSorterSearch(options?: MatchSorterOptions): SearchEngine;
interface MatchSorterOptions {
    /** match-sorter ranking threshold */
    threshold?: number;
    /** Additional keys to search */
    keys?: string[];
}

export { type MatchSorterOptions, createMatchSorterSearch };