@butlerw/vellum 0.1.0

package/src/tui/components/session/SessionListPanel.tsx

@@ -0,0 +1,252 @@
+/**
+ * SessionListPanel Component (T056)
+ *
+ * Displays a scrollable list of sessions with keyboard navigation.
+ *
+ * @module tui/components/session/SessionListPanel
+ */
+
+import { Box, Text, useInput } from "ink";
+import type React from "react";
+import { useCallback, useMemo, useState } from "react";
+import { useTheme } from "../../theme/index.js";
+import { SessionItem } from "./SessionItem.js";
+import type { SessionListPanelProps } from "./types.js";
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+/** Default maximum height for the session list */
+const DEFAULT_MAX_HEIGHT = 10;
+
+/** Number of sessions to skip when using page up/down */
+const PAGE_SIZE = 5;
+
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+/**
+ * Calculate visible sessions based on scroll position and max height.
+ */
+function getVisibleSessions<T>(
+  sessions: readonly T[],
+  scrollOffset: number,
+  maxVisible: number
+): readonly T[] {
+  return sessions.slice(scrollOffset, scrollOffset + maxVisible);
+}
+
+// =============================================================================
+// Main Component
+// =============================================================================
+
+/**
+ * SessionListPanel displays a scrollable list of sessions.
+ *
+ * Features:
+ * - j/k or arrow keys for navigation
+ * - Page up/down support
+ * - Home/End to jump to first/last
+ * - Visual scroll indicators
+ * - Highlights selected and active sessions
+ *
+ * @example
+ * ```tsx
+ * <SessionListPanel
+ *   sessions={sessionList}
+ *   selectedSessionId="sess-1"
+ *   activeSessionId="sess-2"
+ *   onSelectSession={(id) => handleSelect(id)}
+ *   maxHeight={10}
+ *   isFocused={true}
+ * />
+ * ```
+ */
+export function SessionListPanel({
+  sessions,
+  selectedSessionId,
+  activeSessionId,
+  onSelectSession,
+  maxHeight = DEFAULT_MAX_HEIGHT,
+  isFocused = true,
+}: SessionListPanelProps): React.JSX.Element {
+  const { theme } = useTheme();
+
+  // Track the index of the selected session
+  const [selectedIndex, setSelectedIndex] = useState(() => {
+    if (selectedSessionId) {
+      const index = sessions.findIndex((s) => s.id === selectedSessionId);
+      return index >= 0 ? index : 0;
+    }
+    return 0;
+  });
+
+  // Track scroll offset for virtualization
+  const [scrollOffset, setScrollOffset] = useState(0);
+
+  // Calculate visible items (account for header)
+  const maxVisible = Math.max(1, maxHeight - 2);
+
+  // Get visible sessions based on scroll
+  const visibleSessions = useMemo(
+    () => getVisibleSessions(sessions, scrollOffset, maxVisible),
+    [sessions, scrollOffset, maxVisible]
+  );
+
+  // Check if we can scroll
+  const canScrollUp = scrollOffset > 0;
+  const canScrollDown = scrollOffset + maxVisible < sessions.length;
+
+  /**
+   * Navigate to a specific index, adjusting scroll as needed.
+   */
+  const navigateToIndex = useCallback(
+    (newIndex: number) => {
+      // Clamp index to valid range
+      const clampedIndex = Math.max(0, Math.min(newIndex, sessions.length - 1));
+      setSelectedIndex(clampedIndex);
+
+      // Adjust scroll to keep selection visible
+      if (clampedIndex < scrollOffset) {
+        setScrollOffset(clampedIndex);
+      } else if (clampedIndex >= scrollOffset + maxVisible) {
+        setScrollOffset(clampedIndex - maxVisible + 1);
+      }
+
+      // Notify parent of selection change
+      if (onSelectSession && sessions[clampedIndex]) {
+        onSelectSession(sessions[clampedIndex].id);
+      }
+    },
+    [sessions, scrollOffset, maxVisible, onSelectSession]
+  );
+
+  /**
+   * Check if key matches navigation down.
+   */
+  const isNavigateDown = (input: string, key: { downArrow: boolean }) =>
+    input === "j" || key.downArrow;
+
+  /**
+   * Check if key matches navigation up.
+   */
+  const isNavigateUp = (input: string, key: { upArrow: boolean }) => input === "k" || key.upArrow;
+
+  /**
+   * Check if key matches page navigation.
+   */
+  const isPageNav = (
+    input: string,
+    key: { pageDown?: boolean; pageUp?: boolean; ctrl?: boolean }
+  ): "down" | "up" | null => {
+    if (key.pageDown || (key.ctrl && input === "d")) return "down";
+    if (key.pageUp || (key.ctrl && input === "u")) return "up";
+    return null;
+  };
+
+  // Handle keyboard input
+  useInput(
+    (input, key) => {
+      if (isNavigateDown(input, key)) {
+        navigateToIndex(selectedIndex + 1);
+        return;
+      }
+      if (isNavigateUp(input, key)) {
+        navigateToIndex(selectedIndex - 1);
+        return;
+      }
+      const pageDir = isPageNav(input, key);
+      if (pageDir === "down") {
+        navigateToIndex(selectedIndex + PAGE_SIZE);
+        return;
+      }
+      if (pageDir === "up") {
+        navigateToIndex(selectedIndex - PAGE_SIZE);
+        return;
+      }
+      // g/G: vim-style jump to first/last
+      if (input === "g") {
+        navigateToIndex(0);
+        return;
+      }
+      if (input === "G") {
+        navigateToIndex(sessions.length - 1);
+      }
+    },
+    { isActive: isFocused }
+  );
+
+  const textColor = theme.semantic.text.primary;
+  const mutedColor = theme.semantic.text.muted;
+  const borderColor = theme.semantic.border.default;
+
+  // Empty state
+  if (sessions.length === 0) {
+    return (
+      <Box
+        flexDirection="column"
+        borderStyle="single"
+        borderColor={borderColor}
+        paddingX={1}
+        height={maxHeight}
+      >
+        <Text color={textColor} bold>
+          Sessions
+        </Text>
+        <Box flexGrow={1} justifyContent="center" alignItems="center">
+          <Text color={mutedColor} italic>
+            No sessions found
+          </Text>
+        </Box>
+      </Box>
+    );
+  }
+
+  return (
+    <Box
+      flexDirection="column"
+      borderStyle="single"
+      borderColor={borderColor}
+      paddingX={1}
+      height={maxHeight}
+    >
+      {/* Header with scroll indicators */}
+      <Box flexDirection="row" justifyContent="space-between">
+        <Text color={textColor} bold>
+          Sessions ({sessions.length})
+        </Text>
+        <Box flexDirection="row" gap={1}>
+          {canScrollUp && <Text color={mutedColor}>↑</Text>}
+          {canScrollDown && <Text color={mutedColor}>↓</Text>}
+        </Box>
+      </Box>
+
+      {/* Session list */}
+      <Box flexDirection="column" flexGrow={1} overflow="hidden">
+        {visibleSessions.map((session, visibleIndex) => {
+          const actualIndex = scrollOffset + visibleIndex;
+          return (
+            <SessionItem
+              key={session.id}
+              session={session}
+              isSelected={actualIndex === selectedIndex}
+              isActive={session.id === activeSessionId}
+              onSelect={onSelectSession}
+            />
+          );
+        })}
+      </Box>
+
+      {/* Footer with navigation hints */}
+      <Box marginTop={0}>
+        <Text color={mutedColor} dimColor>
+          j/k: navigate • Enter: select • g/G: first/last
+        </Text>
+      </Box>
+    </Box>
+  );
+}
+
+export default SessionListPanel;

package/src/tui/components/session/SessionPicker.tsx

@@ -0,0 +1,449 @@
+/**
+ * SessionPicker Component (T056)
+ *
+ * Modal dialog for selecting a session from the session list.
+ * Triggered by Ctrl+S keybinding.
+ *
+ * @module tui/components/session/SessionPicker
+ */
+
+import { getIcons } from "@vellum/shared";
+import { Box, Text, useInput } from "ink";
+import type React from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useTheme } from "../../theme/index.js";
+import { truncateToDisplayWidth } from "../../utils/index.js";
+import { SessionPreview } from "./SessionPreview.js";
+import type { SessionMetadata, SessionPickerProps, SessionPreviewMessage } from "./types.js";
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+/** Maximum height for the session list */
+const LIST_MAX_HEIGHT = 12;
+
+/** Maximum height for the preview panel */
+const PREVIEW_MAX_HEIGHT = 6;
+
+/** Page size for navigation */
+const PAGE_SIZE = 5;
+
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+/**
+ * Format timestamp for session item display.
+ */
+function formatTimestamp(date: Date): string {
+  const now = new Date();
+  const isToday =
+    date.getDate() === now.getDate() &&
+    date.getMonth() === now.getMonth() &&
+    date.getFullYear() === now.getFullYear();
+
+  if (isToday) {
+    return date.toLocaleTimeString(undefined, {
+      hour: "2-digit",
+      minute: "2-digit",
+    });
+  }
+
+  return date.toLocaleDateString(undefined, {
+    month: "short",
+    day: "numeric",
+  });
+}
+
+/**
+ * Truncate text with ellipsis.
+ * Uses string-width for accurate CJK/Emoji handling.
+ */
+function truncateText(text: string, maxLength: number): string {
+  return truncateToDisplayWidth(text, maxLength);
+}
+
+/**
+ * Build a minimal preview from session metadata.
+ * Used as a graceful fallback when message preview data is unavailable.
+ */
+function buildFallbackPreviewMessages(session: SessionMetadata): SessionPreviewMessage[] {
+  const messages: SessionPreviewMessage[] = [];
+
+  messages.push({
+    id: `${session.id}-preview-fallback-title`,
+    role: "user",
+    content: session.title,
+    timestamp: new Date(Math.max(0, session.timestamp.getTime() - 60000)),
+  });
+
+  if (session.lastMessage) {
+    messages.push({
+      id: `${session.id}-preview-fallback-last`,
+      role: "assistant",
+      content: session.lastMessage,
+      timestamp: session.timestamp,
+    });
+  }
+
+  return messages;
+}
+
+// =============================================================================
+// Sub-Components
+// =============================================================================
+
+/**
+ * Session list item in the picker.
+ */
+interface PickerItemProps {
+  readonly session: SessionMetadata;
+  readonly isSelected: boolean;
+  readonly isActive: boolean;
+  readonly primaryColor: string;
+  readonly textColor: string;
+  readonly mutedColor: string;
+  readonly successColor: string;
+}
+
+function PickerItem({
+  session,
+  isSelected,
+  isActive,
+  primaryColor,
+  textColor,
+  mutedColor,
+  successColor,
+}: PickerItemProps): React.JSX.Element {
+  const indicator = isSelected ? "▶" : isActive ? "●" : " ";
+  const indicatorColor = isSelected ? primaryColor : isActive ? successColor : mutedColor;
+  const displayTitle = truncateText(session.title, 35);
+
+  return (
+    <Box flexDirection="row" paddingX={1}>
+      <Text color={indicatorColor}>{indicator} </Text>
+      <Box flexDirection="row" justifyContent="space-between" flexGrow={1}>
+        <Text color={isSelected ? primaryColor : textColor} bold={isSelected}>
+          {displayTitle}
+        </Text>
+        <Box flexDirection="row" gap={1}>
+          <Text dimColor>({session.messageCount})</Text>
+          <Text color={mutedColor}>{formatTimestamp(session.timestamp)}</Text>
+        </Box>
+      </Box>
+    </Box>
+  );
+}
+
+// =============================================================================
+// Main Component
+// =============================================================================
+
+/**
+ * SessionPicker is a modal dialog for selecting sessions.
+ *
+ * Features:
+ * - j/k or arrow keys for navigation
+ * - Enter to select session
+ * - Escape or q to close
+ * - Preview panel shows selected session messages
+ * - Page up/down for faster navigation
+ * - g/G to jump to first/last
+ *
+ * @example
+ * ```tsx
+ * <SessionPicker
+ *   sessions={sessionList}
+ *   activeSessionId="current-session"
+ *   onSelect={(id) => switchToSession(id)}
+ *   onClose={() => setPickerOpen(false)}
+ *   isOpen={pickerOpen}
+ * />
+ * ```
+ */
+export function SessionPicker({
+  sessions,
+  activeSessionId,
+  loadPreviewMessages,
+  onSelect,
+  onClose,
+  isOpen,
+}: SessionPickerProps): React.JSX.Element | null {
+  const { theme } = useTheme();
+
+  // Track selection index
+  const [selectedIndex, setSelectedIndex] = useState(0);
+
+  // Track scroll offset
+  const [scrollOffset, setScrollOffset] = useState(0);
+
+  // Prevent double-handling of input
+  const handledRef = useRef(false);
+
+  // Calculate visible sessions
+  const maxVisible = LIST_MAX_HEIGHT - 4; // Account for header, footer, borders
+
+  const visibleSessions = useMemo(
+    () => sessions.slice(scrollOffset, scrollOffset + maxVisible),
+    [sessions, scrollOffset, maxVisible]
+  );
+
+  // Get selected session
+  const selectedSession = sessions[selectedIndex];
+
+  // Preview messages cache and state (performance: cache per session id)
+  const previewCacheRef = useRef<Map<string, readonly SessionPreviewMessage[]>>(new Map());
+  const [previewMessages, setPreviewMessages] = useState<readonly SessionPreviewMessage[]>([]);
+  const previewRequestIdRef = useRef(0);
+
+  // Keep preview messages in sync with selected session.
+  // Uses cache when available; otherwise loads via loadPreviewMessages and stores per id.
+  useEffect(() => {
+    if (!isOpen) {
+      return;
+    }
+
+    if (!selectedSession) {
+      setPreviewMessages([]);
+      return;
+    }
+
+    const cached = previewCacheRef.current.get(selectedSession.id);
+    if (cached) {
+      setPreviewMessages(cached);
+      return;
+    }
+
+    previewRequestIdRef.current += 1;
+    const requestId = previewRequestIdRef.current;
+
+    const load = async () => {
+      if (!loadPreviewMessages) {
+        const fallback = buildFallbackPreviewMessages(selectedSession);
+        previewCacheRef.current.set(selectedSession.id, fallback);
+        if (previewRequestIdRef.current === requestId) {
+          setPreviewMessages(fallback);
+        }
+        return;
+      }
+
+      try {
+        const loaded = await loadPreviewMessages(selectedSession.id);
+        const messages = loaded ?? buildFallbackPreviewMessages(selectedSession);
+        previewCacheRef.current.set(selectedSession.id, messages);
+        if (previewRequestIdRef.current === requestId) {
+          setPreviewMessages(messages);
+        }
+      } catch {
+        const fallback = buildFallbackPreviewMessages(selectedSession);
+        previewCacheRef.current.set(selectedSession.id, fallback);
+        if (previewRequestIdRef.current === requestId) {
+          setPreviewMessages(fallback);
+        }
+      }
+    };
+
+    void load();
+  }, [isOpen, selectedSession, loadPreviewMessages]);
+
+  // Scroll indicators
+  const canScrollUp = scrollOffset > 0;
+  const canScrollDown = scrollOffset + maxVisible < sessions.length;
+
+  /**
+   * Navigate to a specific index.
+   */
+  const navigateToIndex = useCallback(
+    (newIndex: number) => {
+      const clampedIndex = Math.max(0, Math.min(newIndex, sessions.length - 1));
+      setSelectedIndex(clampedIndex);
+
+      // Adjust scroll to keep selection visible
+      if (clampedIndex < scrollOffset) {
+        setScrollOffset(clampedIndex);
+      } else if (clampedIndex >= scrollOffset + maxVisible) {
+        setScrollOffset(clampedIndex - maxVisible + 1);
+      }
+    },
+    [sessions.length, scrollOffset, maxVisible]
+  );
+
+  /**
+   * Handle close action with double-handling prevention.
+   */
+  const handleClose = useCallback(() => {
+    if (handledRef.current) return false;
+    handledRef.current = true;
+    onClose();
+    setTimeout(() => {
+      handledRef.current = false;
+    }, 0);
+    return true;
+  }, [onClose]);
+
+  /**
+   * Handle select action with double-handling prevention.
+   */
+  const handleSelect = useCallback(() => {
+    if (handledRef.current || !selectedSession) return false;
+    handledRef.current = true;
+    onSelect(selectedSession.id);
+    setTimeout(() => {
+      handledRef.current = false;
+    }, 0);
+    return true;
+  }, [onSelect, selectedSession]);
+
+  /**
+   * Check navigation direction from key input.
+   */
+  const getNavDirection = (
+    input: string,
+    key: {
+      downArrow: boolean;
+      upArrow: boolean;
+      pageDown?: boolean;
+      pageUp?: boolean;
+      ctrl?: boolean;
+    }
+  ): number | null => {
+    if (input === "j" || key.downArrow) return 1;
+    if (input === "k" || key.upArrow) return -1;
+    if (key.pageDown || (key.ctrl && input === "d")) return PAGE_SIZE;
+    if (key.pageUp || (key.ctrl && input === "u")) return -PAGE_SIZE;
+    if (input === "g") return -selectedIndex; // Jump to 0
+    if (input === "G") return sessions.length - 1 - selectedIndex; // Jump to end
+    return null;
+  };
+
+  // Handle keyboard input
+  useInput(
+    (input, key) => {
+      if (handledRef.current) return;
+
+      // Close: Escape or q
+      if (key.escape || input.toLowerCase() === "q") {
+        handleClose();
+        return;
+      }
+
+      // Select: Enter
+      if (key.return) {
+        handleSelect();
+        return;
+      }
+
+      // Navigation
+      const delta = getNavDirection(input, key);
+      if (delta !== null) {
+        navigateToIndex(selectedIndex + delta);
+      }
+    },
+    { isActive: isOpen }
+  );
+
+  // Don't render if not open
+  if (!isOpen) {
+    return null;
+  }
+
+  const textColor = theme.semantic.text.primary;
+  const mutedColor = theme.semantic.text.muted;
+  const primaryColor = theme.colors.primary;
+  const successColor = theme.colors.success;
+
+  // Empty state
+  if (sessions.length === 0) {
+    return (
+      <Box
+        flexDirection="column"
+        borderStyle="double"
+        borderColor={primaryColor}
+        paddingX={2}
+        paddingY={1}
+      >
+        <Text color={textColor} bold>
+          {getIcons().plan} Select Session
+        </Text>
+        <Box marginY={1}>
+          <Text color={mutedColor} italic>
+            No sessions available
+          </Text>
+        </Box>
+        <Text color={mutedColor} dimColor>
+          Press <Text bold>Esc</Text> or <Text bold>q</Text> to close
+        </Text>
+      </Box>
+    );
+  }
+
+  return (
+    <Box flexDirection="column">
+      {/* Main modal */}
+      <Box
+        flexDirection="column"
+        borderStyle="double"
+        borderColor={primaryColor}
+        paddingX={1}
+        paddingY={0}
+      >
+        {/* Header */}
+        <Box flexDirection="row" justifyContent="space-between" marginBottom={1}>
+          <Text color={textColor} bold>
+            {getIcons().plan} Select Session ({sessions.length})
+          </Text>
+          <Box flexDirection="row" gap={1}>
+            {canScrollUp && <Text color={mutedColor}>↑</Text>}
+            {canScrollDown && <Text color={mutedColor}>↓</Text>}
+          </Box>
+        </Box>
+
+        {/* Session list */}
+        <Box flexDirection="column">
+          {visibleSessions.map((session, visibleIndex) => {
+            const actualIndex = scrollOffset + visibleIndex;
+            return (
+              <PickerItem
+                key={session.id}
+                session={session}
+                isSelected={actualIndex === selectedIndex}
+                isActive={session.id === activeSessionId}
+                primaryColor={primaryColor}
+                textColor={textColor}
+                mutedColor={mutedColor}
+                successColor={successColor}
+              />
+            );
+          })}
+        </Box>
+
+        {/* Footer with keybindings */}
+        <Box marginTop={1} flexDirection="row" gap={2}>
+          <Text color={mutedColor} dimColor>
+            <Text bold>j/k</Text> navigate
+          </Text>
+          <Text color={mutedColor} dimColor>
+            <Text bold>Enter</Text> select
+          </Text>
+          <Text color={mutedColor} dimColor>
+            <Text bold>Esc/q</Text> close
+          </Text>
+        </Box>
+      </Box>
+
+      {/* Preview panel */}
+      {selectedSession && (
+        <Box marginTop={1}>
+          <SessionPreview
+            messages={previewMessages}
+            title={selectedSession.title}
+            maxHeight={PREVIEW_MAX_HEIGHT}
+          />
+        </Box>
+      )}
+    </Box>
+  );
+}
+
+export default SessionPicker;