@principal-ade/panel-layouts 0.1.6 → 0.2.1

package/dist/index.d.ts

@@ -3,8 +3,13 @@ import { EditableConfigurablePanelLayout } from '@principal-ade/panels';
 import { EditableConfigurablePanelLayoutProps } from '@principal-ade/panels';
 import { mapThemeToPanelVars } from '@principal-ade/panels';
 import { mapThemeToTabVars } from '@principal-ade/panels';
+import { PanelActions } from '@principal-ade/panel-framework-core';
+import { PanelBlurEventPayload } from '@principal-ade/panel-framework-core';
+import { PanelContextValue } from '@principal-ade/panel-framework-core';
 import { PanelDefinition } from '@principal-ade/panels';
 import { PanelDefinitionWithContent } from '@principal-ade/panels';
+import { PanelEventEmitter } from '@principal-ade/panel-framework-core';
+import { PanelFocusEventPayload } from '@principal-ade/panel-framework-core';
 import { PanelGroup } from '@principal-ade/panels';
 import { PanelLayout } from '@principal-ade/panels';
 import { PanelSlot } from '@principal-ade/panels';
@@ -19,6 +24,241 @@ import { TilesConfig } from '@principal-ade/panels';
  */
 export declare type BuiltInWorkspaceId = 'project-management' | 'code-review' | 'documentation' | 'agent-work' | 'quality-check' | 'drawing' | 'old-school' | 'principal-office';
 
+/**
+ * Command definition for the command palette
+ */
+export declare interface Command {
+    /** Unique identifier for the command */
+    id: string;
+    /** Display label shown in the command list */
+    label: string;
+    /** Optional description shown below the label */
+    description?: string;
+    /** Optional icon (string or React element) */
+    icon?: string | React.ReactNode;
+    /** Keywords for fuzzy search matching */
+    keywords?: string[];
+    /** Category for grouping commands */
+    category?: string;
+    /** Optional keyboard shortcut hint (e.g., "Alt+1") */
+    shortcut?: string;
+    /** Command execution function */
+    execute: (context: CommandContext) => void | Promise<void>;
+    /** Optional function to determine if command is available */
+    isAvailable?: (context: CommandContext) => boolean;
+    /** Priority for ordering (higher = appears first) */
+    priority?: number;
+}
+
+/**
+ * Command category definition
+ */
+export declare interface CommandCategory {
+    /** Category identifier */
+    id: string;
+    /** Display label */
+    label: string;
+    /** Display priority (higher = shown first) */
+    priority?: number;
+    /** Optional icon */
+    icon?: string | React.ReactNode;
+}
+
+/**
+ * Context provided to command execution functions
+ */
+export declare interface CommandContext {
+    /** Panel framework context */
+    panelContext: PanelContextValue;
+    /** Panel actions for navigation, file operations, etc. */
+    actions: PanelActions;
+    /** Event bus for inter-panel communication */
+    events: PanelEventEmitter;
+    /** Currently focused panel */
+    focusedPanel: PanelSlotId | null;
+    /** Function to set panel focus */
+    setFocus: (panel: PanelSlotId) => void;
+    /** Workspace management service */
+    workspaceService?: WorkspaceLayoutService;
+    /** Close the command palette */
+    closeCommandPalette: () => void;
+}
+
+/**
+ * CommandInput - Input field for the command palette
+ * Auto-focuses on mount and handles input changes
+ */
+export declare const CommandInput: default_2.FC<CommandInputProps>;
+
+declare interface CommandInputProps {
+    value: string;
+    onChange: (value: string) => void;
+    placeholder?: string;
+    onClose: () => void;
+    onEnter?: () => void;
+}
+
+/**
+ * CommandItem - Individual command item in the list
+ * Displays command label, description, icon, and keyboard shortcut
+ */
+export declare const CommandItem: default_2.ForwardRefExoticComponent<CommandItemProps & default_2.RefAttributes<HTMLDivElement>>;
+
+declare interface CommandItemProps {
+    command: Command;
+    isSelected: boolean;
+    onClick: () => void;
+    onMouseEnter: () => void;
+}
+
+/**
+ * CommandList - List of filtered commands
+ * Displays commands grouped by category with keyboard navigation support
+ */
+export declare const CommandList: default_2.FC<CommandListProps>;
+
+declare interface CommandListProps {
+    commands: Command[];
+    selectedIndex: number;
+    onSelect: (command: Command) => void;
+    onHover: (index: number) => void;
+    maxResults?: number;
+}
+
+/**
+ * CommandPalette - Vim-style command palette component
+ * Displays at the bottom of the screen with an input field and command list
+ */
+export declare const CommandPalette: default_2.FC<CommandPaletteProps>;
+
+/**
+ * Configuration options for the command palette
+ */
+export declare interface CommandPaletteConfig {
+    /** Custom keyboard shortcut configuration */
+    keyboard?: CommandPaletteKeyboardConfig;
+    /** Maximum number of results to show */
+    maxResults?: number;
+    /** Placeholder text for the input field */
+    placeholder?: string;
+    /** Custom CSS class for the container */
+    className?: string;
+    /** Custom styles for the container */
+    style?: React.CSSProperties;
+    /** Maximum height of the results list */
+    maxHeight?: string;
+    /** Enable fuzzy search (default: true) */
+    fuzzySearch?: boolean;
+    /** Threshold for fuzzy search matching (0-1, default: 0.3) */
+    fuzzyThreshold?: number;
+}
+
+/**
+ * Keyboard shortcut configuration for triggering the command palette
+ */
+export declare interface CommandPaletteKeyboardConfig {
+    /** Key to trigger the command palette (default: ' ' for Space) */
+    key?: string;
+    /** Require Alt key (default: true) */
+    altKey?: boolean;
+    /** Require Ctrl key (default: false) */
+    ctrlKey?: boolean;
+    /** Require Meta/Cmd key (default: false) */
+    metaKey?: boolean;
+    /** Require Shift key (default: false) */
+    shiftKey?: boolean;
+}
+
+/**
+ * Props for the CommandPalette component
+ */
+export declare interface CommandPaletteProps {
+    /** Command palette hook return value */
+    commandPalette: UseCommandPaletteReturn;
+    /** Configuration options */
+    config?: CommandPaletteConfig;
+    /** Panel context for command execution */
+    context: CommandContext;
+}
+
+/**
+ * Service for managing command registration and execution
+ * Provides a centralized registry for commands that can be accessed via the command palette
+ */
+export declare class CommandRegistryService {
+    private commands;
+    private listeners;
+    /**
+     * Register one or more commands
+     * @param commands - Array of commands to register
+     */
+    registerCommands(commands: Command[]): void;
+    /**
+     * Register a single command
+     * @param command - Command to register
+     */
+    registerCommand(command: Command): void;
+    /**
+     * Unregister commands by ID
+     * @param commandIds - Array of command IDs to unregister
+     */
+    unregisterCommands(commandIds: string[]): void;
+    /**
+     * Unregister a single command
+     * @param commandId - Command ID to unregister
+     */
+    unregisterCommand(commandId: string): void;
+    /**
+     * Get all registered commands
+     * @param context - Command context for availability checks
+     * @returns Array of available commands
+     */
+    getCommands(context?: CommandContext): Command[];
+    /**
+     * Get a command by ID
+     * @param commandId - Command ID
+     * @returns Command if found, undefined otherwise
+     */
+    getCommand(commandId: string): Command | undefined;
+    /**
+     * Execute a command by ID
+     * @param commandId - Command ID to execute
+     * @param context - Command context
+     */
+    executeCommand(commandId: string, context: CommandContext): Promise<void>;
+    /**
+     * Search commands by query
+     * @param query - Search query
+     * @param context - Command context for availability checks
+     * @returns Filtered and sorted commands
+     */
+    searchCommands(query: string, context?: CommandContext): Command[];
+    /**
+     * Sort commands by priority and label
+     * @param commands - Commands to sort
+     * @returns Sorted commands
+     */
+    private sortCommands;
+    /**
+     * Subscribe to registry changes
+     * @param listener - Callback function called when registry changes
+     * @returns Unsubscribe function
+     */
+    subscribe(listener: () => void): () => void;
+    /**
+     * Clear all commands
+     */
+    clear(): void;
+    /**
+     * Get count of registered commands
+     */
+    get size(): number;
+    /**
+     * Notify all listeners of registry changes
+     */
+    private notifyListeners;
+}
+
 /**
  * Options for creating a new workspace
  */
@@ -57,6 +297,18 @@ export declare interface FocusIndicatorProps {
     style?: default_2.CSSProperties;
 }
 
+/**
+ * Get the global command registry instance
+ * @returns Global CommandRegistryService instance
+ */
+export declare function getGlobalCommandRegistry(): CommandRegistryService;
+
+/**
+ * Get panel commands
+ * @returns Array of panel-related commands
+ */
+export declare function getPanelCommands(): Command[];
+
 /**
  * Default localStorage-based persistence adapter for web applications
  */
@@ -97,6 +349,8 @@ export { mapThemeToPanelVars }
 
 export { mapThemeToTabVars }
 
+export { PanelBlurEventPayload }
+
 /**
  * Collapsed state for panels
  */
@@ -105,6 +359,11 @@ export declare interface PanelCollapsed {
     right?: boolean;
 }
 
+/**
+ * Built-in commands for panel navigation and control
+ */
+export declare const panelCommands: Command[];
+
 export { PanelDefinition }
 
 export { PanelDefinitionWithContent }
@@ -123,6 +382,8 @@ export declare interface PanelFocusActions {
     focusPrevious: () => void;
 }
 
+export { PanelFocusEventPayload }
+
 /**
  * Focus state for the panel layout
  */
@@ -212,6 +473,11 @@ export declare interface RepositoryWorkspaceState {
     };
 }
 
+/**
+ * Reset the global command registry (useful for testing)
+ */
+export declare function resetGlobalCommandRegistry(): void;
+
 export { ResponsiveConfigurablePanelLayout }
 
 export { ResponsiveConfigurablePanelLayoutProps }
@@ -276,11 +542,97 @@ export declare interface UpdateWorkspaceOptions {
     };
 }
 
+/**
+ * Hook for managing command palette state and behavior
+ * Handles command registration, filtering, keyboard navigation, and execution
+ */
+export declare function useCommandPalette({ context, commands: initialCommands, keyboard, config, registry: providedRegistry, }: UseCommandPaletteProps): UseCommandPaletteReturn;
+
+declare interface UseCommandPaletteProps {
+    /** Command context */
+    context: CommandContext;
+    /** Initial commands to register */
+    commands?: Command[];
+    /** Keyboard configuration */
+    keyboard?: CommandPaletteKeyboardConfig;
+    /** Command palette configuration */
+    config?: CommandPaletteConfig;
+    /** Command registry service (optional, uses global if not provided) */
+    registry?: CommandRegistryService;
+}
+
+/**
+ * Command palette state and actions hook return type
+ */
+export declare interface UseCommandPaletteReturn {
+    /** Whether the command palette is open */
+    isOpen: boolean;
+    /** Open the command palette */
+    open: () => void;
+    /** Close the command palette */
+    close: () => void;
+    /** Toggle the command palette */
+    toggle: () => void;
+    /** Search query */
+    query: string;
+    /** Set search query */
+    setQuery: (query: string) => void;
+    /** Filtered and sorted commands */
+    filteredCommands: Command[];
+    /** Execute a command by ID */
+    executeCommand: (commandId: string) => Promise<void>;
+    /** Selected command index (for keyboard navigation) */
+    selectedIndex: number;
+    /** Set selected index */
+    setSelectedIndex: (index: number) => void;
+    /** Navigate to next command */
+    selectNext: () => void;
+    /** Navigate to previous command */
+    selectPrevious: () => void;
+    /** Execute the currently selected command */
+    executeSelected: () => Promise<void>;
+    /** All registered commands */
+    commands: Command[];
+    /** Register new commands */
+    registerCommands: (commands: Command[]) => void;
+    /** Unregister commands by ID */
+    unregisterCommands: (commandIds: string[]) => void;
+}
+
 /**
  * Hook for managing panel focus state with keyboard shortcuts
  */
 export declare function usePanelFocus(options?: UsePanelFocusOptions): UsePanelFocusReturn;
 
+/**
+ * Hook for panels to listen to focus events from the framework
+ *
+ * This is a convenience hook that panels can use to respond to focus changes
+ * from keyboard shortcuts, mouse clicks, or programmatic navigation.
+ *
+ * @param panelId - The ID of this panel (from panel metadata)
+ * @param events - Event emitter from PanelComponentProps
+ * @param onFocus - Callback when this panel receives focus
+ * @param onBlur - Optional callback when this panel loses focus
+ *
+ * @example
+ * ```typescript
+ * function TerminalPanel({ context, actions, events }: PanelComponentProps) {
+ *   const xtermRef = useRef<Terminal>();
+ *
+ *   usePanelFocusListener(
+ *     'terminal',
+ *     events,
+ *     () => xtermRef.current?.focus(),
+ *     () => xtermRef.current?.blur()
+ *   );
+ *
+ *   return <div id="xterm-container" />;
+ * }
+ * ```
+ */
+export declare function usePanelFocusListener(panelId: string, events: PanelEventEmitter, onFocus: () => void, onBlur?: () => void): void;
+
 export declare interface UsePanelFocusOptions {
     /** Initial focused panel (optional) */
     initialFocus?: PanelSlotId | null;
@@ -290,6 +642,10 @@ export declare interface UsePanelFocusOptions {
     panelType?: 'two-panel' | 'three-panel';
     /** Callback when focus changes */
     onFocusChange?: (panel: PanelSlotId | null) => void;
+    /** Event emitter from panel framework (optional, for focus events) */
+    events?: PanelEventEmitter;
+    /** Function to map panel slot to panel ID (optional, required for event emission) */
+    getPanelId?: (slot: PanelSlotId) => string | undefined;
 }
 
 export declare interface UsePanelFocusReturn extends PanelFocusState, PanelFocusActions {