@mdxui/terminal 2.0.0

package/dist/storybook/index.d.ts

@@ -0,0 +1,396 @@
+import { I as InteractiveRenderer, a as InteractiveRendererConfig } from '../interactive-D0JkWosD.js';
+import React__default from 'react';
+import { Decorator } from '@storybook/react';
+
+/**
+ * @mdxui/terminal Keyboard Simulator
+ *
+ * Provides utilities for simulating keyboard events in Storybook stories
+ * for testing interactive terminal components.
+ *
+ * @packageDocumentation
+ *
+ * @example
+ * ```tsx
+ * import { createKeyboardSimulator, KeySequence } from '@mdxui/terminal/storybook'
+ *
+ * const simulator = createKeyboardSimulator({ renderer })
+ *
+ * // Single key press
+ * simulator.press('enter')
+ *
+ * // Key with modifiers
+ * simulator.press('s', { ctrl: true })
+ *
+ * // Predefined sequences
+ * simulator.sequence(KeySequence.NAVIGATE_DOWN_3)
+ * ```
+ */
+
+/**
+ * Key modifiers for keyboard events
+ */
+interface KeyModifiers {
+    /** Ctrl key pressed */
+    ctrl?: boolean;
+    /** Alt/Option key pressed */
+    alt?: boolean;
+    /** Shift key pressed */
+    shift?: boolean;
+    /** Meta/Command key pressed */
+    meta?: boolean;
+}
+/**
+ * Single key press event
+ */
+interface KeyPress {
+    /** Key name (e.g., 'enter', 'tab', 'a', 'escape') */
+    key: string;
+    /** Key modifiers */
+    modifiers?: KeyModifiers;
+    /** Delay in ms before this key press (default: 0) */
+    delay?: number;
+}
+/**
+ * Configuration for the keyboard simulator
+ */
+interface KeyboardSimulatorConfig {
+    /** Interactive renderer instance */
+    renderer: InteractiveRenderer;
+    /** Default delay between key presses in ms (default: 0) */
+    defaultDelay?: number;
+    /** Callback when key is pressed */
+    onKeyPress?: (key: string, modifiers: KeyModifiers) => void;
+    /** Callback when sequence completes */
+    onSequenceComplete?: (sequence: KeyPress[]) => void;
+}
+/**
+ * Keyboard simulator instance
+ */
+interface KeyboardSimulator {
+    /** Press a single key */
+    press(key: string, modifiers?: KeyModifiers): void;
+    /** Press a key and return a promise that resolves after the default delay */
+    pressAsync(key: string, modifiers?: KeyModifiers): Promise<void>;
+    /** Execute a sequence of key presses */
+    sequence(keys: KeyPress[]): void;
+    /** Execute a sequence of key presses with delays */
+    sequenceAsync(keys: KeyPress[]): Promise<void>;
+    /** Type a string character by character */
+    type(text: string): void;
+    /** Type a string character by character with delays */
+    typeAsync(text: string, charDelay?: number): Promise<void>;
+    /** Reset simulator state */
+    reset(): void;
+    /** Get list of pressed keys (for assertions) */
+    getPressedKeys(): string[];
+    /** Clear pressed keys history */
+    clearHistory(): void;
+}
+/**
+ * Common key sequences for testing navigation patterns
+ */
+declare const KeySequence: {
+    /** Navigate down one item */
+    readonly NAVIGATE_DOWN: KeyPress[];
+    /** Navigate down three items */
+    readonly NAVIGATE_DOWN_3: KeyPress[];
+    /** Navigate up one item */
+    readonly NAVIGATE_UP: KeyPress[];
+    /** Navigate up three items */
+    readonly NAVIGATE_UP_3: KeyPress[];
+    /** Tab forward through focusables */
+    readonly TAB_FORWARD: KeyPress[];
+    /** Tab forward three times */
+    readonly TAB_FORWARD_3: KeyPress[];
+    /** Tab backward through focusables */
+    readonly TAB_BACKWARD: KeyPress[];
+    /** Tab backward three times */
+    readonly TAB_BACKWARD_3: KeyPress[];
+    /** Select/activate focused element */
+    readonly SELECT: KeyPress[];
+    /** Toggle focused element (e.g., checkbox) */
+    readonly TOGGLE: KeyPress[];
+    /** Cancel/escape current action */
+    readonly CANCEL: KeyPress[];
+    /** Navigate to first item (vim: gg) */
+    readonly GOTO_FIRST: KeyPress[];
+    /** Navigate to last item (vim: G) */
+    readonly GOTO_LAST: KeyPress[];
+    /** Open search mode (vim: /) */
+    readonly SEARCH: KeyPress[];
+    /** Navigate down and select */
+    readonly NAVIGATE_DOWN_SELECT: KeyPress[];
+    /** Navigate to next item using j (vim) */
+    readonly VIM_DOWN: KeyPress[];
+    /** Navigate to previous item using k (vim) */
+    readonly VIM_UP: KeyPress[];
+    /** Navigate left using h (vim) */
+    readonly VIM_LEFT: KeyPress[];
+    /** Navigate right using l (vim) */
+    readonly VIM_RIGHT: KeyPress[];
+    /** Delete sequence (vim: dd) */
+    readonly VIM_DELETE: KeyPress[];
+    /** Home key - jump to beginning */
+    readonly HOME: KeyPress[];
+    /** End key - jump to end */
+    readonly END: KeyPress[];
+    /** Page down */
+    readonly PAGE_DOWN: KeyPress[];
+    /** Page up */
+    readonly PAGE_UP: KeyPress[];
+    /** Ctrl+C - cancel/interrupt */
+    readonly INTERRUPT: KeyPress[];
+    /** Ctrl+S - save */
+    readonly SAVE: KeyPress[];
+};
+/**
+ * Creates a keyboard simulator for testing interactive terminal components.
+ *
+ * The simulator wraps the interactive renderer's `emitKey` method and provides
+ * higher-level abstractions for common keyboard testing patterns.
+ *
+ * @param config - Simulator configuration
+ * @returns Keyboard simulator instance
+ *
+ * @example
+ * ```tsx
+ * const renderer = await createInteractiveRenderer({ vimBindings: true })
+ * const simulator = createKeyboardSimulator({ renderer })
+ *
+ * // Register some focusable elements
+ * renderer.registerFocusable('item-1', { tabIndex: 0 })
+ * renderer.registerFocusable('item-2', { tabIndex: 0 })
+ * renderer.registerFocusable('item-3', { tabIndex: 0 })
+ *
+ * // Focus first item
+ * renderer.focusById('item-1')
+ *
+ * // Navigate down using simulator
+ * simulator.press('j')  // vim down
+ * expect(renderer.getFocusedId()).toBe('item-2')
+ *
+ * // Or use predefined sequences
+ * simulator.sequence(KeySequence.NAVIGATE_DOWN)
+ * expect(renderer.getFocusedId()).toBe('item-3')
+ * ```
+ */
+declare function createKeyboardSimulator(config: KeyboardSimulatorConfig): KeyboardSimulator;
+/**
+ * Assert that a specific key was pressed
+ */
+declare function expectKeyPressed(simulator: KeyboardSimulator, key: string, modifiers?: KeyModifiers): void;
+/**
+ * Assert that a sequence of keys was pressed in order
+ */
+declare function expectSequencePressed(simulator: KeyboardSimulator, sequence: KeyPress[]): void;
+/**
+ * Assert that no keys were pressed
+ */
+declare function expectNoKeysPressed(simulator: KeyboardSimulator): void;
+/**
+ * Assert total number of key presses
+ */
+declare function expectKeyPressCount(simulator: KeyboardSimulator, count: number): void;
+/**
+ * Map DOM KeyboardEvent to our key format
+ */
+declare function mapDOMKeyEvent(event: KeyboardEvent): KeyPress;
+/**
+ * Create a keyboard event handler for DOM events that forwards to simulator
+ */
+declare function createDOMKeyHandler(simulator: KeyboardSimulator, options?: {
+    /** Prevent default browser behavior */
+    preventDefault?: boolean;
+    /** Stop event propagation */
+    stopPropagation?: boolean;
+    /** Keys to ignore (don't forward to simulator) */
+    ignoreKeys?: string[];
+}): (event: KeyboardEvent) => void;
+
+/**
+ * @mdxui/terminal Interactive Decorator
+ *
+ * Storybook decorator and utilities for testing interactive terminal components.
+ * Provides keyboard event capture and visual feedback for navigation testing.
+ *
+ * @packageDocumentation
+ *
+ * @example
+ * ```tsx
+ * // In your story file
+ * import type { Meta, StoryObj } from '@storybook/react'
+ * import { InteractiveDecorator, useKeyboardNavigation } from '@mdxui/terminal/storybook'
+ * import { Select } from './Select'
+ *
+ * const meta: Meta<typeof Select> = {
+ *   title: 'Terminal/Select',
+ *   component: Select,
+ *   decorators: [InteractiveDecorator],
+ *   parameters: {
+ *     interactive: {
+ *       vimBindings: true,
+ *       showKeyLog: true,
+ *     },
+ *   },
+ * }
+ * ```
+ */
+
+/**
+ * Parameters for the interactive decorator
+ */
+interface InteractiveDecoratorParameters {
+    /** Interactive renderer configuration */
+    interactive?: InteractiveRendererConfig & {
+        /** Show key press log panel */
+        showKeyLog?: boolean;
+        /** Maximum key log entries to display */
+        maxKeyLogEntries?: number;
+        /** Show focus indicator overlay */
+        showFocusOverlay?: boolean;
+        /** Keys to ignore from DOM forwarding */
+        ignoreKeys?: string[];
+        /** Auto-focus the interactive container */
+        autoFocus?: boolean;
+    };
+}
+/**
+ * Interactive context for stories
+ */
+interface InteractiveContext {
+    /** The interactive renderer instance */
+    renderer: InteractiveRenderer | null;
+    /** The keyboard simulator instance */
+    simulator: KeyboardSimulator | null;
+    /** List of pressed keys */
+    keyLog: string[];
+    /** Currently focused element ID */
+    focusedId: string | null;
+    /** Clear the key log */
+    clearKeyLog: () => void;
+}
+/**
+ * Context for accessing interactive state in stories
+ */
+declare const InteractiveContext: React__default.Context<InteractiveContext>;
+/**
+ * Hook to access interactive context in story components
+ */
+declare function useInteractiveContext(): InteractiveContext;
+/**
+ * Storybook decorator for interactive terminal component testing.
+ *
+ * This decorator:
+ * - Creates an InteractiveRenderer instance
+ * - Captures keyboard events from the DOM
+ * - Forwards them to the renderer
+ * - Optionally shows a key log panel for debugging
+ * - Provides context for accessing the renderer/simulator in stories
+ *
+ * @example
+ * ```tsx
+ * // meta configuration
+ * const meta: Meta<typeof MyComponent> = {
+ *   title: 'Terminal/MyComponent',
+ *   component: MyComponent,
+ *   decorators: [InteractiveDecorator],
+ *   parameters: {
+ *     interactive: {
+ *       vimBindings: true,
+ *       showKeyLog: true,
+ *       maxKeyLogEntries: 10,
+ *     },
+ *   },
+ * }
+ *
+ * // Access context in story
+ * export const Interactive: Story = {
+ *   render: () => {
+ *     const { renderer, simulator } = useInteractiveContext()
+ *     // Use renderer/simulator in your component
+ *     return <MyComponent renderer={renderer} />
+ *   },
+ * }
+ * ```
+ */
+declare const InteractiveDecorator: Decorator;
+/**
+ * Hook for stories that need manual keyboard navigation setup.
+ *
+ * Use this when you need more control over the keyboard handling
+ * or don't want to use the decorator.
+ *
+ * @example
+ * ```tsx
+ * function MyInteractiveStory() {
+ *   const { renderer, simulator, keyLog, containerProps } = useKeyboardNavigation({
+ *     vimBindings: true,
+ *   })
+ *
+ *   useEffect(() => {
+ *     if (!renderer) return
+ *
+ *     renderer.registerFocusable('item-1', { tabIndex: 0 })
+ *     renderer.registerFocusable('item-2', { tabIndex: 0 })
+ *     renderer.focusById('item-1')
+ *   }, [renderer])
+ *
+ *   return (
+ *     <div {...containerProps}>
+ *       <div data-focused={renderer?.getFocusedId() === 'item-1'}>Item 1</div>
+ *       <div data-focused={renderer?.getFocusedId() === 'item-2'}>Item 2</div>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+declare function useKeyboardNavigation(config?: InteractiveRendererConfig): {
+    renderer: InteractiveRenderer | null;
+    simulator: KeyboardSimulator | null;
+    keyLog: string[];
+    focusedId: string | null;
+    clearKeyLog: () => void;
+    containerProps: {
+        ref: React__default.RefObject<HTMLDivElement>;
+        tabIndex: number;
+        onKeyDown: (event: React__default.KeyboardEvent<HTMLDivElement>) => void;
+        onFocus: () => void;
+        style: React__default.CSSProperties;
+    };
+};
+/**
+ * Programmatically simulate keyboard navigation in a story.
+ *
+ * Useful for creating animated demos or testing specific navigation flows.
+ *
+ * @example
+ * ```tsx
+ * export const AnimatedDemo: Story = {
+ *   render: () => {
+ *     const { renderer, simulator } = useInteractiveContext()
+ *
+ *     useEffect(() => {
+ *       if (!simulator) return
+ *
+ *       // Simulate navigation sequence
+ *       const cleanup = simulateKeyboardDemo(simulator, [
+ *         { keys: [{ key: 'tab' }], delay: 500 },
+ *         { keys: [{ key: 'tab' }], delay: 500 },
+ *         { keys: [{ key: 'enter' }], delay: 500 },
+ *       ])
+ *
+ *       return cleanup
+ *     }, [simulator])
+ *
+ *     return <MyComponent />
+ *   },
+ * }
+ * ```
+ */
+declare function simulateKeyboardDemo(simulator: KeyboardSimulator, steps: Array<{
+    keys: KeyPress[];
+    delay: number;
+}>): () => void;
+
+export { InteractiveContext, InteractiveContext as InteractiveContextType, InteractiveDecorator, type InteractiveDecoratorParameters, type KeyModifiers, type KeyPress, KeySequence, type KeyboardSimulator, type KeyboardSimulatorConfig, createDOMKeyHandler, createKeyboardSimulator, expectKeyPressCount, expectKeyPressed, expectNoKeysPressed, expectSequencePressed, mapDOMKeyEvent, simulateKeyboardDemo, useInteractiveContext, useKeyboardNavigation };