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;
}
/** Metadata for a route command, colocated in route definitions */
interface RouteCommandMeta {
    /** Display label (falls back to path-derived label) */
    label?: string;
    /** Description text */
    description?: string;
    /** Additional search keywords */
    keywords?: string[];
    /** Group ID */
    group?: string;
    /** Icon — string, emoji, or React element */
    icon?: ReactNode;
    /** Required permissions */
    permissions?: string[];
    /** Ordering priority */
    priority?: number;
    /** Whether to hide from palette */
    hidden?: boolean;
}

/**
 * A React Router route object shape (compatible with v6 and v7).
 * We only use the fields we need for scanning.
 */
interface RouteObject {
    path?: string;
    children?: RouteObject[];
    handle?: {
        command?: RouteCommandMeta;
        [key: string]: unknown;
    };
    [key: string]: unknown;
}
/** An exclude pattern — exact string, glob with *, or RegExp */
type ExcludePattern = string | RegExp;
/** Options for scanRoutes */
interface ScanRoutesOptions {
    /**
     * Patterns to exclude from command discovery (merged with defaults).
     * Supports exact strings, globs with * (e.g. '/admin/*'), and RegExp.
     */
    exclude?: ExcludePattern[];
    /** Set to true to skip the default exclude list */
    noDefaultExclude?: boolean;
    /** Include routes with dynamic segments like :id or [id] (default: false) */
    includeDynamic?: boolean;
}
/**
 * Scan a React Router route tree and extract command items.
 *
 * Walks the route tree recursively. For each route with a path,
 * creates a CommandItem. If the route has `handle.command` metadata,
 * uses it to enrich the item.
 *
 * @param routes - React Router route objects
 * @param options - Scan options (exclude paths, etc.)
 * @returns Array of discovered command items
 */
declare function scanRoutes(routes: RouteObject[], options?: ScanRoutesOptions | string): CommandItem[];

export { type RouteObject, scanRoutes };