@supernal/interface-nextjs 0.1.1

package/dist/index.d.mts

@@ -0,0 +1,299 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React from 'react';
+import { NavigationGraph, NavigationPath, NavigationContext, ToolMetadata } from '@supernal/interface/browser';
+import { AIInterface } from '@supernal/interface';
+export { AICommand, AIResponse } from '@supernal/interface';
+
+interface SupernalProviderProps {
+    children: React.ReactNode;
+    theme?: 'light' | 'dark' | 'auto';
+    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+    mode?: 'fuzzy' | 'ai';
+    apiKey?: string;
+    welcomeMessage?: string;
+    routes?: Record<string, string>;
+    disabled?: boolean;
+    onNavigate?: (context: string) => void;
+    onToolExecute?: (tool: string, result: any) => void;
+}
+declare function SupernalProvider({ children, theme, position, mode, apiKey, welcomeMessage, routes, disabled, onNavigate, onToolExecute, }: SupernalProviderProps): react_jsx_runtime.JSX.Element;
+
+interface ChatInputContextType {
+    /**
+     * Insert text into the chat input (and optionally submit it)
+     */
+    insertText: (text: string, submit?: boolean) => void;
+    /**
+     * Register the chat input element (called by ChatBubble)
+     */
+    registerInput: (callback: (text: string, submit?: boolean) => void) => void;
+}
+declare function useChatInput(): ChatInputContextType;
+declare function ChatInputProvider({ children }: {
+    children: React.ReactNode;
+}): react_jsx_runtime.JSX.Element;
+
+declare function NavigationContextProvider({ value, children }: {
+    value: string;
+    children: React.ReactNode;
+}): react_jsx_runtime.JSX.Element;
+/**
+ * Hook to access the NavigationGraph singleton
+ */
+declare function useNavigationGraph(): NavigationGraph;
+/**
+ * Hook to get the current navigation context
+ *
+ * @example
+ * const currentContext = useCurrentContext();
+ * console.log(currentContext); // 'dashboard.security'
+ */
+declare function useCurrentContext(): string;
+/**
+ * Hook to register a tool in a navigation context
+ *
+ * @param toolId - Unique tool identifier
+ * @param contextId - Optional: explicit context ID (otherwise uses current context)
+ * @param metadata - Optional: metadata for auto-detection
+ *
+ * @example
+ * // Auto-registers in current context
+ * useRegisterTool('enable-2fa');
+ *
+ * // Or explicit context
+ * useRegisterTool('enable-2fa', 'dashboard.security');
+ *
+ * // Or with auto-detection metadata
+ * useRegisterTool('enable-2fa', undefined, {
+ *   filePath: 'src/pages/dashboard/SecurityTab.tsx'
+ * });
+ */
+declare function useRegisterTool(toolId: string, contextId?: string, metadata?: {
+    filePath?: string;
+    componentName?: string;
+    element?: Element;
+}): void;
+/**
+ * Hook to compute navigation path from current context to target
+ *
+ * @param targetContextOrToolId - Target context ID or tool ID
+ * @param isToolId - Whether the target is a tool ID (will lookup context)
+ *
+ * @example
+ * const { path, loading, error } = useNavigationPath('dashboard.security');
+ *
+ * if (loading) return <Spinner />;
+ * if (error) return <Error message={error} />;
+ * if (!path) return <div>Cannot navigate</div>;
+ *
+ * return (
+ *   <div>
+ *     Path: {path.steps.map(s => s.navigationTool).join(' → ')}
+ *   </div>
+ * );
+ */
+declare function useNavigationPath(targetContextOrToolId: string, isToolId?: boolean): {
+    path: NavigationPath | null;
+    loading: boolean;
+    error: string | undefined;
+};
+/**
+ * Hook to execute navigation to a target context
+ *
+ * @example
+ * const { navigateTo, navigating, error } = useNavigate();
+ *
+ * const handleClick = async () => {
+ *   const success = await navigateTo('dashboard.security');
+ *   if (success) {
+ *     console.log('Navigation complete!');
+ *   }
+ * };
+ */
+declare function useNavigate(): {
+    navigateTo: (targetContextOrToolId: string, isToolId?: boolean, executeNavigation?: (toolId: string) => Promise<void>) => Promise<boolean>;
+    navigating: boolean;
+    error: string | undefined;
+};
+/**
+ * Hook to get all navigation contexts (for debugging/admin UI)
+ *
+ * @example
+ * const contexts = useAllContexts();
+ *
+ * return (
+ *   <ul>
+ *     {contexts.map(ctx => (
+ *       <li key={ctx.id}>
+ *         {ctx.name} - {ctx.tools.length} tools
+ *       </li>
+ *     ))}
+ *   </ul>
+ * );
+ */
+declare function useAllContexts(): NavigationContext[];
+
+interface Message {
+    id: string;
+    text: string;
+    type: 'user' | 'ai' | 'system';
+    timestamp: string;
+}
+interface ChatContextType {
+    messages: Message[];
+    sendMessage: (text: string) => Promise<void>;
+    clearMessages: () => void;
+    isLoading: boolean;
+}
+declare function useChatContext(): ChatContextType;
+declare function ChatProvider({ children, mode, apiKey, onToolExecute, }: {
+    children: React.ReactNode;
+    mode?: 'fuzzy' | 'ai';
+    apiKey?: string;
+    onToolExecute?: (tool: string, result: any) => void;
+}): react_jsx_runtime.JSX.Element;
+
+/**
+ * Persistent Chat Bubble Component
+ *
+ * Fixed position chat bubble in lower right corner that:
+ * - Appears on every page
+ * - Expands/collapses without blocking content
+ * - Provides AI interface for tool execution
+ */
+
+interface ChatBubbleProps {
+    theme?: 'light' | 'dark' | 'auto';
+    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+    welcomeMessage?: string;
+}
+declare const ChatBubble: React.FC<ChatBubbleProps>;
+
+interface AutoNavigationContextProps {
+    children: React.ReactNode;
+    routes?: Record<string, string>;
+    onNavigate?: (context: string) => void;
+}
+declare function AutoNavigationContext({ children, routes, onNavigate, }: AutoNavigationContextProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Tool Manager - Centralized system for tool execution and feedback
+ *
+ * Tools auto-report execution → ToolManager listens → Updates UI
+ */
+interface ToolExecutionResult {
+    toolName: string;
+    elementId?: string;
+    actionType?: string;
+    success: boolean;
+    message: string;
+    data?: unknown;
+    error?: Error;
+    timestamp: string;
+}
+type ToolExecutionListener = (result: ToolExecutionResult) => void;
+declare class ToolManagerClass {
+    private listeners;
+    private lastReport;
+    constructor();
+    /**
+     * Subscribe to tool execution results
+     */
+    subscribe(listener: ToolExecutionListener): () => void;
+    /**
+     * Tools call this to report execution results (auto-called by HOCs)
+     */
+    reportExecution(result: Omit<ToolExecutionResult, 'timestamp'> | ToolExecutionResult): void;
+    /**
+     * Get the last reported tool execution (for AIInterface)
+     */
+    getLastReport(): ToolExecutionResult | null;
+    /**
+     * Clear the last report
+     */
+    clearLastReport(): void;
+    /**
+     * Helper to create a success result (for custom messages)
+     */
+    success(toolName: string, message: string, data?: unknown): ToolExecutionResult;
+    /**
+     * Helper to create a failure result (for custom messages)
+     */
+    failure(toolName: string, message: string, data?: unknown): ToolExecutionResult;
+}
+declare const ToolManager: ToolManagerClass;
+
+/**
+ * Demo AI Interface - uses open-source AIInterface
+ *
+ * This is a thin wrapper that:
+ * 1. Imports the generic AIInterface from @supernal/interface
+ * 2. Hooks into app-specific ToolManager for UI notifications
+ * 3. Provides backward-compatible interface for existing code
+ */
+
+interface CommandResult {
+    success: boolean;
+    message: string;
+    tool?: any;
+}
+/**
+ * Demo-specific AIInterface with ToolManager integration
+ */
+declare class DemoAIInterface extends AIInterface {
+    private toolExecutionListeners;
+    constructor();
+    /**
+     * Subscribe to tool execution results (for chat UI)
+     */
+    onToolExecution(callback: (result: ToolExecutionResult) => void): () => void;
+    /**
+     * Notify all listeners about tool execution
+     */
+    private notifyToolExecutionListeners;
+    /**
+     * Find and execute command - backward compatible wrapper
+     *
+     * Convenience method that combines findToolsForCommand and executeCommand
+     */
+    findAndExecuteCommand(query: string, _currentContainer?: string): Promise<CommandResult>;
+}
+
+/**
+ * Fuzzy Matching Utility
+ * Finds items that best match a search query
+ */
+declare class FuzzyMatcher {
+    /**
+     * Find item that best matches the query
+     */
+    static findBest<T>(items: T[], query: string, getSearchableText: (item: T) => string[]): T | null;
+    /**
+     * Find all items that match the query (ranked by relevance)
+     */
+    static findAll<T>(items: T[], query: string, getSearchableText: (item: T) => string[]): T[];
+}
+
+/**
+ * Fuzzy Matching Utilities
+ *
+ * Shared fuzzy matching logic used by both:
+ * - DemoAIInterface (client-side tool matching)
+ * - CopilotKit mock endpoint (server-side fallback)
+ */
+
+interface FuzzyMatchResult {
+    tool: ToolMetadata | undefined;
+    score: number;
+    confidence: number;
+}
+/**
+ * Score how well a query matches a tool's examples, description, and method name
+ */
+declare function scoreToolMatch(query: string, tool: ToolMetadata): number;
+/**
+ * Find the best matching tool from a list
+ */
+declare function findBestMatch(query: string, tools: ToolMetadata[]): FuzzyMatchResult;
+
+export { AutoNavigationContext, ChatBubble, ChatInputProvider, ChatProvider, type CommandResult, DemoAIInterface, type FuzzyMatchResult, FuzzyMatcher, NavigationContextProvider, SupernalProvider, type SupernalProviderProps, type ToolExecutionResult, ToolManager, findBestMatch, scoreToolMatch, useAllContexts, useChatContext, useChatInput, useCurrentContext, useNavigate, useNavigationGraph, useNavigationPath, useRegisterTool };

package/dist/index.d.ts

@@ -0,0 +1,299 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React from 'react';
+import { NavigationGraph, NavigationPath, NavigationContext, ToolMetadata } from '@supernal/interface/browser';
+import { AIInterface } from '@supernal/interface';
+export { AICommand, AIResponse } from '@supernal/interface';
+
+interface SupernalProviderProps {
+    children: React.ReactNode;
+    theme?: 'light' | 'dark' | 'auto';
+    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+    mode?: 'fuzzy' | 'ai';
+    apiKey?: string;
+    welcomeMessage?: string;
+    routes?: Record<string, string>;
+    disabled?: boolean;
+    onNavigate?: (context: string) => void;
+    onToolExecute?: (tool: string, result: any) => void;
+}
+declare function SupernalProvider({ children, theme, position, mode, apiKey, welcomeMessage, routes, disabled, onNavigate, onToolExecute, }: SupernalProviderProps): react_jsx_runtime.JSX.Element;
+
+interface ChatInputContextType {
+    /**
+     * Insert text into the chat input (and optionally submit it)
+     */
+    insertText: (text: string, submit?: boolean) => void;
+    /**
+     * Register the chat input element (called by ChatBubble)
+     */
+    registerInput: (callback: (text: string, submit?: boolean) => void) => void;
+}
+declare function useChatInput(): ChatInputContextType;
+declare function ChatInputProvider({ children }: {
+    children: React.ReactNode;
+}): react_jsx_runtime.JSX.Element;
+
+declare function NavigationContextProvider({ value, children }: {
+    value: string;
+    children: React.ReactNode;
+}): react_jsx_runtime.JSX.Element;
+/**
+ * Hook to access the NavigationGraph singleton
+ */
+declare function useNavigationGraph(): NavigationGraph;
+/**
+ * Hook to get the current navigation context
+ *
+ * @example
+ * const currentContext = useCurrentContext();
+ * console.log(currentContext); // 'dashboard.security'
+ */
+declare function useCurrentContext(): string;
+/**
+ * Hook to register a tool in a navigation context
+ *
+ * @param toolId - Unique tool identifier
+ * @param contextId - Optional: explicit context ID (otherwise uses current context)
+ * @param metadata - Optional: metadata for auto-detection
+ *
+ * @example
+ * // Auto-registers in current context
+ * useRegisterTool('enable-2fa');
+ *
+ * // Or explicit context
+ * useRegisterTool('enable-2fa', 'dashboard.security');
+ *
+ * // Or with auto-detection metadata
+ * useRegisterTool('enable-2fa', undefined, {
+ *   filePath: 'src/pages/dashboard/SecurityTab.tsx'
+ * });
+ */
+declare function useRegisterTool(toolId: string, contextId?: string, metadata?: {
+    filePath?: string;
+    componentName?: string;
+    element?: Element;
+}): void;
+/**
+ * Hook to compute navigation path from current context to target
+ *
+ * @param targetContextOrToolId - Target context ID or tool ID
+ * @param isToolId - Whether the target is a tool ID (will lookup context)
+ *
+ * @example
+ * const { path, loading, error } = useNavigationPath('dashboard.security');
+ *
+ * if (loading) return <Spinner />;
+ * if (error) return <Error message={error} />;
+ * if (!path) return <div>Cannot navigate</div>;
+ *
+ * return (
+ *   <div>
+ *     Path: {path.steps.map(s => s.navigationTool).join(' → ')}
+ *   </div>
+ * );
+ */
+declare function useNavigationPath(targetContextOrToolId: string, isToolId?: boolean): {
+    path: NavigationPath | null;
+    loading: boolean;
+    error: string | undefined;
+};
+/**
+ * Hook to execute navigation to a target context
+ *
+ * @example
+ * const { navigateTo, navigating, error } = useNavigate();
+ *
+ * const handleClick = async () => {
+ *   const success = await navigateTo('dashboard.security');
+ *   if (success) {
+ *     console.log('Navigation complete!');
+ *   }
+ * };
+ */
+declare function useNavigate(): {
+    navigateTo: (targetContextOrToolId: string, isToolId?: boolean, executeNavigation?: (toolId: string) => Promise<void>) => Promise<boolean>;
+    navigating: boolean;
+    error: string | undefined;
+};
+/**
+ * Hook to get all navigation contexts (for debugging/admin UI)
+ *
+ * @example
+ * const contexts = useAllContexts();
+ *
+ * return (
+ *   <ul>
+ *     {contexts.map(ctx => (
+ *       <li key={ctx.id}>
+ *         {ctx.name} - {ctx.tools.length} tools
+ *       </li>
+ *     ))}
+ *   </ul>
+ * );
+ */
+declare function useAllContexts(): NavigationContext[];
+
+interface Message {
+    id: string;
+    text: string;
+    type: 'user' | 'ai' | 'system';
+    timestamp: string;
+}
+interface ChatContextType {
+    messages: Message[];
+    sendMessage: (text: string) => Promise<void>;
+    clearMessages: () => void;
+    isLoading: boolean;
+}
+declare function useChatContext(): ChatContextType;
+declare function ChatProvider({ children, mode, apiKey, onToolExecute, }: {
+    children: React.ReactNode;
+    mode?: 'fuzzy' | 'ai';
+    apiKey?: string;
+    onToolExecute?: (tool: string, result: any) => void;
+}): react_jsx_runtime.JSX.Element;
+
+/**
+ * Persistent Chat Bubble Component
+ *
+ * Fixed position chat bubble in lower right corner that:
+ * - Appears on every page
+ * - Expands/collapses without blocking content
+ * - Provides AI interface for tool execution
+ */
+
+interface ChatBubbleProps {
+    theme?: 'light' | 'dark' | 'auto';
+    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+    welcomeMessage?: string;
+}
+declare const ChatBubble: React.FC<ChatBubbleProps>;
+
+interface AutoNavigationContextProps {
+    children: React.ReactNode;
+    routes?: Record<string, string>;
+    onNavigate?: (context: string) => void;
+}
+declare function AutoNavigationContext({ children, routes, onNavigate, }: AutoNavigationContextProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Tool Manager - Centralized system for tool execution and feedback
+ *
+ * Tools auto-report execution → ToolManager listens → Updates UI
+ */
+interface ToolExecutionResult {
+    toolName: string;
+    elementId?: string;
+    actionType?: string;
+    success: boolean;
+    message: string;
+    data?: unknown;
+    error?: Error;
+    timestamp: string;
+}
+type ToolExecutionListener = (result: ToolExecutionResult) => void;
+declare class ToolManagerClass {
+    private listeners;
+    private lastReport;
+    constructor();
+    /**
+     * Subscribe to tool execution results
+     */
+    subscribe(listener: ToolExecutionListener): () => void;
+    /**
+     * Tools call this to report execution results (auto-called by HOCs)
+     */
+    reportExecution(result: Omit<ToolExecutionResult, 'timestamp'> | ToolExecutionResult): void;
+    /**
+     * Get the last reported tool execution (for AIInterface)
+     */
+    getLastReport(): ToolExecutionResult | null;
+    /**
+     * Clear the last report
+     */
+    clearLastReport(): void;
+    /**
+     * Helper to create a success result (for custom messages)
+     */
+    success(toolName: string, message: string, data?: unknown): ToolExecutionResult;
+    /**
+     * Helper to create a failure result (for custom messages)
+     */
+    failure(toolName: string, message: string, data?: unknown): ToolExecutionResult;
+}
+declare const ToolManager: ToolManagerClass;
+
+/**
+ * Demo AI Interface - uses open-source AIInterface
+ *
+ * This is a thin wrapper that:
+ * 1. Imports the generic AIInterface from @supernal/interface
+ * 2. Hooks into app-specific ToolManager for UI notifications
+ * 3. Provides backward-compatible interface for existing code
+ */
+
+interface CommandResult {
+    success: boolean;
+    message: string;
+    tool?: any;
+}
+/**
+ * Demo-specific AIInterface with ToolManager integration
+ */
+declare class DemoAIInterface extends AIInterface {
+    private toolExecutionListeners;
+    constructor();
+    /**
+     * Subscribe to tool execution results (for chat UI)
+     */
+    onToolExecution(callback: (result: ToolExecutionResult) => void): () => void;
+    /**
+     * Notify all listeners about tool execution
+     */
+    private notifyToolExecutionListeners;
+    /**
+     * Find and execute command - backward compatible wrapper
+     *
+     * Convenience method that combines findToolsForCommand and executeCommand
+     */
+    findAndExecuteCommand(query: string, _currentContainer?: string): Promise<CommandResult>;
+}
+
+/**
+ * Fuzzy Matching Utility
+ * Finds items that best match a search query
+ */
+declare class FuzzyMatcher {
+    /**
+     * Find item that best matches the query
+     */
+    static findBest<T>(items: T[], query: string, getSearchableText: (item: T) => string[]): T | null;
+    /**
+     * Find all items that match the query (ranked by relevance)
+     */
+    static findAll<T>(items: T[], query: string, getSearchableText: (item: T) => string[]): T[];
+}
+
+/**
+ * Fuzzy Matching Utilities
+ *
+ * Shared fuzzy matching logic used by both:
+ * - DemoAIInterface (client-side tool matching)
+ * - CopilotKit mock endpoint (server-side fallback)
+ */
+
+interface FuzzyMatchResult {
+    tool: ToolMetadata | undefined;
+    score: number;
+    confidence: number;
+}
+/**
+ * Score how well a query matches a tool's examples, description, and method name
+ */
+declare function scoreToolMatch(query: string, tool: ToolMetadata): number;
+/**
+ * Find the best matching tool from a list
+ */
+declare function findBestMatch(query: string, tools: ToolMetadata[]): FuzzyMatchResult;
+
+export { AutoNavigationContext, ChatBubble, ChatInputProvider, ChatProvider, type CommandResult, DemoAIInterface, type FuzzyMatchResult, FuzzyMatcher, NavigationContextProvider, SupernalProvider, type SupernalProviderProps, type ToolExecutionResult, ToolManager, findBestMatch, scoreToolMatch, useAllContexts, useChatContext, useChatInput, useCurrentContext, useNavigate, useNavigationGraph, useNavigationPath, useRegisterTool };