@mdxui/terminal 2.0.0

package/src/storybook/interactive-decorator.tsx

@@ -0,0 +1,659 @@
+/**
+ * @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,
+ *     },
+ *   },
+ * }
+ * ```
+ */
+
+import React, { useEffect, useState, useCallback, useRef } from 'react'
+import type { Decorator } from '@storybook/react'
+import { createInteractiveRenderer } from '../renderers/interactive'
+import type { InteractiveRenderer, InteractiveRendererConfig } from '../renderers/interactive'
+import {
+  createKeyboardSimulator,
+  createDOMKeyHandler,
+  type KeyboardSimulator,
+  type KeyPress,
+} from './keyboard-simulator'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Parameters for the interactive decorator
+ */
+export 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
+ */
+export 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
+}
+
+// ============================================================================
+// React Context
+// ============================================================================
+
+/**
+ * Context for accessing interactive state in stories
+ */
+export const InteractiveContext = React.createContext<InteractiveContext>({
+  renderer: null,
+  simulator: null,
+  keyLog: [],
+  focusedId: null,
+  clearKeyLog: () => {},
+})
+
+/**
+ * Hook to access interactive context in story components
+ */
+export function useInteractiveContext(): InteractiveContext {
+  return React.useContext(InteractiveContext)
+}
+
+// ============================================================================
+// Key Log Panel Component
+// ============================================================================
+
+interface KeyLogPanelProps {
+  keyLog: string[]
+  focusedId: string | null
+  onClear: () => void
+}
+
+/**
+ * Visual panel showing key press history and focus state
+ */
+function KeyLogPanel({ keyLog, focusedId, onClear }: KeyLogPanelProps): React.ReactElement {
+  return (
+    <div
+      style={{
+        position: 'fixed',
+        bottom: '16px',
+        right: '16px',
+        width: '240px',
+        maxHeight: '200px',
+        backgroundColor: 'rgba(0, 0, 0, 0.85)',
+        color: '#e5e5e5',
+        borderRadius: '8px',
+        padding: '12px',
+        fontFamily: 'ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace',
+        fontSize: '12px',
+        zIndex: 9999,
+        boxShadow: '0 4px 12px rgba(0, 0, 0, 0.3)',
+      }}
+    >
+      <div
+        style={{
+          display: 'flex',
+          justifyContent: 'space-between',
+          alignItems: 'center',
+          marginBottom: '8px',
+          paddingBottom: '8px',
+          borderBottom: '1px solid rgba(255, 255, 255, 0.1)',
+        }}
+      >
+        <span style={{ fontWeight: 600, color: '#a3e635' }}>Keyboard Log</span>
+        <button
+          onClick={onClear}
+          style={{
+            background: 'transparent',
+            border: 'none',
+            color: '#737373',
+            cursor: 'pointer',
+            fontSize: '11px',
+            padding: '2px 6px',
+          }}
+        >
+          Clear
+        </button>
+      </div>
+
+      {focusedId && (
+        <div
+          style={{
+            marginBottom: '8px',
+            padding: '4px 8px',
+            backgroundColor: 'rgba(163, 230, 53, 0.15)',
+            borderRadius: '4px',
+            color: '#a3e635',
+          }}
+        >
+          Focus: <code style={{ color: '#fde047' }}>{focusedId}</code>
+        </div>
+      )}
+
+      <div
+        style={{
+          maxHeight: '120px',
+          overflowY: 'auto',
+        }}
+      >
+        {keyLog.length === 0 ? (
+          <div style={{ color: '#737373', fontStyle: 'italic' }}>
+            Press keys to see log...
+          </div>
+        ) : (
+          keyLog.map((key, index) => (
+            <div
+              key={`${key}-${index}`}
+              style={{
+                padding: '2px 0',
+                display: 'flex',
+                alignItems: 'center',
+                gap: '8px',
+              }}
+            >
+              <span style={{ color: '#737373' }}>{index + 1}.</span>
+              <code
+                style={{
+                  backgroundColor: 'rgba(255, 255, 255, 0.1)',
+                  padding: '1px 6px',
+                  borderRadius: '3px',
+                  color: '#60a5fa',
+                }}
+              >
+                {key}
+              </code>
+            </div>
+          ))
+        )}
+      </div>
+
+      <div
+        style={{
+          marginTop: '8px',
+          paddingTop: '8px',
+          borderTop: '1px solid rgba(255, 255, 255, 0.1)',
+          color: '#737373',
+          fontSize: '10px',
+        }}
+      >
+        Click container to focus. Use Tab, arrows, vim keys.
+      </div>
+    </div>
+  )
+}
+
+// ============================================================================
+// Interactive Container Component
+// ============================================================================
+
+interface InteractiveContainerProps {
+  children: React.ReactNode
+  config: InteractiveDecoratorParameters['interactive']
+}
+
+/**
+ * Container component that captures keyboard events and provides interactive context
+ */
+function InteractiveContainer({
+  children,
+  config = {},
+}: InteractiveContainerProps): React.ReactElement {
+  const containerRef = useRef<HTMLDivElement>(null)
+  const [renderer, setRenderer] = useState<InteractiveRenderer | null>(null)
+  const [simulator, setSimulator] = useState<KeyboardSimulator | null>(null)
+  const [keyLog, setKeyLog] = useState<string[]>([])
+  const [focusedId, setFocusedId] = useState<string | null>(null)
+
+  const {
+    showKeyLog = true,
+    maxKeyLogEntries = 20,
+    showFocusOverlay = false,
+    ignoreKeys = ['f5', 'f12'],
+    autoFocus = true,
+    ...rendererConfig
+  } = config
+
+  // Initialize renderer and simulator
+  useEffect(() => {
+    let mounted = true
+
+    async function init() {
+      const newRenderer = await createInteractiveRenderer(rendererConfig)
+
+      if (!mounted) {
+        newRenderer.destroy()
+        return
+      }
+
+      const newSimulator = createKeyboardSimulator({
+        renderer: newRenderer,
+        onKeyPress: (key, modifiers) => {
+          const parts: string[] = []
+          if (modifiers.ctrl) parts.push('Ctrl')
+          if (modifiers.alt) parts.push('Alt')
+          if (modifiers.shift) parts.push('Shift')
+          if (modifiers.meta) parts.push('Meta')
+          parts.push(key)
+
+          setKeyLog((prev) => {
+            const newLog = [...prev, parts.join('+')]
+            return newLog.slice(-maxKeyLogEntries)
+          })
+        },
+      })
+
+      setRenderer(newRenderer)
+      setSimulator(newSimulator)
+    }
+
+    init()
+
+    return () => {
+      mounted = false
+      renderer?.destroy()
+    }
+  }, [])
+
+  // Track focus changes
+  useEffect(() => {
+    if (!renderer) return
+
+    const interval = setInterval(() => {
+      const currentFocusedId = renderer.getFocusedId()
+      if (currentFocusedId !== focusedId) {
+        setFocusedId(currentFocusedId)
+      }
+    }, 100)
+
+    return () => clearInterval(interval)
+  }, [renderer, focusedId])
+
+  // Handle DOM keyboard events
+  const handleKeyDown = useCallback(
+    (event: React.KeyboardEvent<HTMLDivElement>) => {
+      if (!simulator) return
+
+      // Create and use DOM handler
+      const handler = createDOMKeyHandler(simulator, {
+        preventDefault: true,
+        stopPropagation: true,
+        ignoreKeys,
+      })
+
+      handler(event.nativeEvent)
+    },
+    [simulator, ignoreKeys]
+  )
+
+  // Handle container focus
+  const handleContainerFocus = useCallback(() => {
+    // Auto-focus first focusable element if nothing is focused
+    if (renderer && !renderer.getFocusedId()) {
+      renderer.focusNext()
+    }
+  }, [renderer])
+
+  // Auto-focus container on mount
+  useEffect(() => {
+    if (autoFocus && containerRef.current) {
+      containerRef.current.focus()
+    }
+  }, [autoFocus, renderer])
+
+  const clearKeyLog = useCallback(() => {
+    setKeyLog([])
+    simulator?.clearHistory()
+  }, [simulator])
+
+  const contextValue: InteractiveContext = {
+    renderer,
+    simulator,
+    keyLog,
+    focusedId,
+    clearKeyLog,
+  }
+
+  return (
+    <InteractiveContext.Provider value={contextValue}>
+      <div
+        ref={containerRef}
+        tabIndex={0}
+        onKeyDown={handleKeyDown}
+        onFocus={handleContainerFocus}
+        style={{
+          outline: 'none',
+          minHeight: '100%',
+          position: 'relative',
+        }}
+        data-interactive-container="true"
+      >
+        {children}
+
+        {showKeyLog && (
+          <KeyLogPanel
+            keyLog={keyLog}
+            focusedId={focusedId}
+            onClear={clearKeyLog}
+          />
+        )}
+
+        {showFocusOverlay && focusedId && (
+          <div
+            style={{
+              position: 'fixed',
+              top: '16px',
+              left: '16px',
+              backgroundColor: 'rgba(163, 230, 53, 0.9)',
+              color: '#000',
+              padding: '4px 8px',
+              borderRadius: '4px',
+              fontFamily: 'ui-monospace, monospace',
+              fontSize: '11px',
+              fontWeight: 600,
+              zIndex: 9998,
+            }}
+          >
+            Focused: {focusedId}
+          </div>
+        )}
+      </div>
+    </InteractiveContext.Provider>
+  )
+}
+
+// ============================================================================
+// Storybook Decorator
+// ============================================================================
+
+/**
+ * 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} />
+ *   },
+ * }
+ * ```
+ */
+export const InteractiveDecorator: Decorator = (Story, context) => {
+  const interactiveParams = context.parameters?.interactive as
+    | InteractiveDecoratorParameters['interactive']
+    | undefined
+
+  return (
+    <InteractiveContainer config={interactiveParams}>
+      <Story />
+    </InteractiveContainer>
+  )
+}
+
+// ============================================================================
+// Hook for Manual Integration
+// ============================================================================
+
+/**
+ * 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>
+ *   )
+ * }
+ * ```
+ */
+export function useKeyboardNavigation(config?: InteractiveRendererConfig): {
+  renderer: InteractiveRenderer | null
+  simulator: KeyboardSimulator | null
+  keyLog: string[]
+  focusedId: string | null
+  clearKeyLog: () => void
+  containerProps: {
+    ref: React.RefObject<HTMLDivElement>
+    tabIndex: number
+    onKeyDown: (event: React.KeyboardEvent<HTMLDivElement>) => void
+    onFocus: () => void
+    style: React.CSSProperties
+  }
+} {
+  const containerRef = useRef<HTMLDivElement>(null)
+  const [renderer, setRenderer] = useState<InteractiveRenderer | null>(null)
+  const [simulator, setSimulator] = useState<KeyboardSimulator | null>(null)
+  const [keyLog, setKeyLog] = useState<string[]>([])
+  const [focusedId, setFocusedId] = useState<string | null>(null)
+
+  // Initialize
+  useEffect(() => {
+    let mounted = true
+
+    async function init() {
+      const newRenderer = await createInteractiveRenderer(config)
+
+      if (!mounted) {
+        newRenderer.destroy()
+        return
+      }
+
+      const newSimulator = createKeyboardSimulator({
+        renderer: newRenderer,
+        onKeyPress: (key, modifiers) => {
+          const parts: string[] = []
+          if (modifiers.ctrl) parts.push('Ctrl')
+          if (modifiers.alt) parts.push('Alt')
+          if (modifiers.shift) parts.push('Shift')
+          if (modifiers.meta) parts.push('Meta')
+          parts.push(key)
+
+          setKeyLog((prev) => [...prev.slice(-19), parts.join('+')])
+        },
+      })
+
+      setRenderer(newRenderer)
+      setSimulator(newSimulator)
+    }
+
+    init()
+
+    return () => {
+      mounted = false
+      renderer?.destroy()
+    }
+  }, [])
+
+  // Track focus
+  useEffect(() => {
+    if (!renderer) return
+
+    const interval = setInterval(() => {
+      setFocusedId(renderer.getFocusedId())
+    }, 100)
+
+    return () => clearInterval(interval)
+  }, [renderer])
+
+  const handleKeyDown = useCallback(
+    (event: React.KeyboardEvent<HTMLDivElement>) => {
+      if (!simulator) return
+
+      const handler = createDOMKeyHandler(simulator, {
+        preventDefault: true,
+        stopPropagation: true,
+      })
+
+      handler(event.nativeEvent)
+    },
+    [simulator]
+  )
+
+  const handleFocus = useCallback(() => {
+    if (renderer && !renderer.getFocusedId()) {
+      renderer.focusNext()
+    }
+  }, [renderer])
+
+  const clearKeyLog = useCallback(() => {
+    setKeyLog([])
+    simulator?.clearHistory()
+  }, [simulator])
+
+  return {
+    renderer,
+    simulator,
+    keyLog,
+    focusedId,
+    clearKeyLog,
+    containerProps: {
+      ref: containerRef,
+      tabIndex: 0,
+      onKeyDown: handleKeyDown,
+      onFocus: handleFocus,
+      style: { outline: 'none' },
+    },
+  }
+}
+
+// ============================================================================
+// Test Utilities for Stories
+// ============================================================================
+
+/**
+ * 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 />
+ *   },
+ * }
+ * ```
+ */
+export function simulateKeyboardDemo(
+  simulator: KeyboardSimulator,
+  steps: Array<{ keys: KeyPress[]; delay: number }>
+): () => void {
+  let cancelled = false
+  const timeouts: ReturnType<typeof setTimeout>[] = []
+
+  let cumulativeDelay = 0
+
+  for (const step of steps) {
+    cumulativeDelay += step.delay
+
+    const timeout = setTimeout(() => {
+      if (!cancelled) {
+        simulator.sequence(step.keys)
+      }
+    }, cumulativeDelay)
+
+    timeouts.push(timeout)
+  }
+
+  return () => {
+    cancelled = true
+    timeouts.forEach((t) => clearTimeout(t))
+  }
+}