@principal-ade/panel-layouts 0.1.5 → 0.2.0

package/dist/index.d.ts

@@ -1,9 +1,13 @@
+import { default as default_2 } from 'react';
 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 { PanelBlurEventPayload } 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';
@@ -40,6 +44,22 @@ export { EditableConfigurablePanelLayout }
 
 export { EditableConfigurablePanelLayoutProps }
 
+/**
+ * Visual indicator that highlights the focused panel
+ *
+ * Renders a subtle border/glow around the focused panel for keyboard navigation feedback
+ */
+export declare const FocusIndicator: default_2.FC<FocusIndicatorProps>;
+
+export declare interface FocusIndicatorProps {
+    /** Whether this panel is currently focused */
+    isFocused: boolean;
+    /** Custom class name */
+    className?: string;
+    /** Custom styles */
+    style?: default_2.CSSProperties;
+}
+
 /**
  * Default localStorage-based persistence adapter for web applications
  */
@@ -80,6 +100,8 @@ export { mapThemeToPanelVars }
 
 export { mapThemeToTabVars }
 
+export { PanelBlurEventPayload }
+
 /**
  * Collapsed state for panels
  */
@@ -92,6 +114,30 @@ export { PanelDefinition }
 
 export { PanelDefinitionWithContent }
 
+/**
+ * Actions for managing panel focus
+ */
+export declare interface PanelFocusActions {
+    /** Set focus to a specific panel */
+    setFocus: (panel: PanelSlotId) => void;
+    /** Clear focus from all panels */
+    clearFocus: () => void;
+    /** Focus the next visible panel */
+    focusNext: () => void;
+    /** Focus the previous visible panel */
+    focusPrevious: () => void;
+}
+
+export { PanelFocusEventPayload }
+
+/**
+ * Focus state for the panel layout
+ */
+export declare interface PanelFocusState {
+    /** Currently focused panel, or null if no panel is focused */
+    focusedPanel: PanelSlotId | null;
+}
+
 export { PanelGroup }
 
 export { PanelLayout }
@@ -116,6 +162,14 @@ export declare interface PanelSizes {
 
 export { PanelSlot }
 
+/**
+ * Focus management type definitions for keyboard shortcuts
+ */
+/**
+ * Panel identifier for focus tracking
+ */
+export declare type PanelSlotId = 'left' | 'middle' | 'right';
+
 /**
  * Storage adapter interface for persisting panel state
  * Implementations can use localStorage, Electron IPC, or remote storage
@@ -229,6 +283,96 @@ export declare interface UpdateWorkspaceOptions {
     };
 }
 
+/**
+ * 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;
+    /** Collapsed state to determine which panels are visible */
+    collapsed?: PanelCollapsed;
+    /** Whether this is a two-panel or three-panel layout */
+    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 {
+    /** Check if a specific panel is focused */
+    isFocused: (panel: PanelSlotId) => boolean;
+}
+
+/**
+ * Hook for handling Alt+1/2/3 keyboard shortcuts for panel toggle and focus
+ *
+ * Behavior:
+ * - Alt+1 (Left Panel):
+ *   1. If collapsed: expand (no focus change)
+ *   2. If expanded but not focused: focus it
+ *   3. If focused: collapse and focus middle
+ *
+ * - Alt+2 (Middle Panel):
+ *   - Always focus middle (never collapses)
+ *
+ * - Alt+3 (Right Panel):
+ *   1. If collapsed: expand (no focus change)
+ *   2. If expanded but not focused: focus it
+ *   3. If focused: collapse and focus middle
+ */
+export declare function usePanelKeyboardShortcuts(options: UsePanelKeyboardShortcutsOptions): void;
+
+export declare interface UsePanelKeyboardShortcutsOptions {
+    /** Whether keyboard shortcuts are enabled */
+    enabled?: boolean;
+    /** Current focused panel */
+    focusedPanel: PanelSlotId | null;
+    /** Current collapsed state */
+    collapsed: PanelCollapsed;
+    /** Panel type (two-panel or three-panel) */
+    panelType: 'two-panel' | 'three-panel';
+    /** Set focus to a specific panel */
+    setFocus: (panel: PanelSlotId) => void;
+    /** Callback to expand a panel */
+    onExpand: (panel: 'left' | 'right') => void | Promise<void>;
+    /** Callback to collapse a panel */
+    onCollapse: (panel: 'left' | 'right') => void | Promise<void>;
+}
+
 /**
  * Hook for persisting panel layouts across sessions
  *