@butlerw/vellum 0.1.0

package/src/tui/tip-integration.ts

@@ -0,0 +1,300 @@
+/**
+ * Tip Engine Integration
+ *
+ * Wires the TipEngine to the TUI application for contextual tips
+ * and progressive disclosure of features.
+ *
+ * @module cli/tui/tip-integration
+ */
+
+import { useCallback, useMemo, useState } from "react";
+import type { Tip, TipContext, TipState } from "../onboarding/index.js";
+import { BUILTIN_TIPS, createTipEngine, TipEngine } from "../onboarding/index.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface TipIntegrationOptions {
+  /** Enable tips display */
+  enabled?: boolean;
+  /** Maximum tips to show per session */
+  maxTipsPerSession?: number;
+  /** Minimum interval between tips (ms) */
+  tipIntervalMs?: number;
+  /** Categories to prioritize */
+  priorityCategories?: string[];
+  /** Callback when a tip is shown */
+  onTipShown?: (tip: Tip) => void;
+  /** Callback when a tip is dismissed */
+  onTipDismissed?: (tipId: string) => void;
+}
+
+export interface TipIntegrationState {
+  /** Current tip to display (null if none) */
+  currentTip: Tip | null;
+  /** Whether tips are enabled */
+  tipsEnabled: boolean;
+  /** Number of tips shown this session */
+  tipsShownCount: number;
+  /** Whether a tip is currently visible */
+  tipVisible: boolean;
+}
+
+export interface TipIntegrationActions {
+  /** Show a contextual tip based on current context */
+  showTip: (context: TipContext) => Tip | null;
+  /** Dismiss the current tip */
+  dismissTip: () => void;
+  /** Permanently dismiss a tip (won't show again) */
+  dismissTipPermanently: (tipId: string) => void;
+  /** Enable or disable tips */
+  setTipsEnabled: (enabled: boolean) => void;
+  /** Get a specific tip by ID */
+  getTip: (tipId: string) => Tip | undefined;
+  /** Check if a tip has been shown */
+  hasTipBeenShown: (tipId: string) => boolean;
+  /** Reset tip states (for testing) */
+  resetTips: () => void;
+}
+
+export type UseTipEngineResult = TipIntegrationState & TipIntegrationActions;
+
+// =============================================================================
+// Default Configuration
+// =============================================================================
+
+const DEFAULT_OPTIONS: Required<TipIntegrationOptions> = {
+  enabled: true,
+  maxTipsPerSession: 10,
+  tipIntervalMs: 60000, // 1 minute between tips
+  priorityCategories: ["shortcuts", "features"],
+  onTipShown: () => {},
+  onTipDismissed: () => {},
+};
+
+// =============================================================================
+// Hook Implementation
+// =============================================================================
+
+/**
+ * React hook for tip engine integration.
+ *
+ * @param options - Tip integration options
+ * @returns Tip integration state and actions
+ *
+ * @example
+ * ```tsx
+ * function AppContent() {
+ *   const {
+ *     currentTip,
+ *     showTip,
+ *     dismissTip,
+ *     tipsEnabled,
+ *   } = useTipEngine({ enabled: true });
+ *
+ *   // Show contextual tips based on user actions
+ *   useEffect(() => {
+ *     showTip({
+ *       currentScreen: "main",
+ *       featureUsageCount: 5,
+ *       recentCommands: ["help", "mode"],
+ *     });
+ *   }, [showTip]);
+ *
+ *   return (
+ *     <>
+ *       {currentTip && (
+ *         <TipBanner tip={currentTip} onDismiss={dismissTip} />
+ *       )}
+ *       <MainContent />
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export function useTipEngine(options: TipIntegrationOptions = {}): UseTipEngineResult {
+  // Memoize config to prevent re-renders from changing object reference
+  // biome-ignore lint/correctness/useExhaustiveDependencies: We intentionally use specific properties to prevent re-renders when only callbacks change
+  const config = useMemo(
+    () => ({ ...DEFAULT_OPTIONS, ...options }),
+    [options.enabled, options.maxTipsPerSession, options.tipIntervalMs]
+  );
+  const { onTipShown, onTipDismissed } = options;
+
+  // Create tip engine instance
+  const tipEngine = useMemo(() => createTipEngine(), []);
+
+  // State
+  const [currentTip, setCurrentTip] = useState<Tip | null>(null);
+  const [tipsEnabled, setTipsEnabled] = useState(config.enabled);
+  const [tipsShownCount, setTipsShownCount] = useState(0);
+  const [tipVisible, setTipVisible] = useState(false);
+  const [lastTipTime, setLastTipTime] = useState(0);
+  const [permanentlyDismissed, setPermanentlyDismissed] = useState<Set<string>>(new Set());
+
+  // Show a tip based on context
+  const showTip = useCallback(
+    (context: TipContext): Tip | null => {
+      if (!tipsEnabled) return null;
+      if (tipsShownCount >= config.maxTipsPerSession) return null;
+
+      // Check tip interval
+      const now = Date.now();
+      if (now - lastTipTime < config.tipIntervalMs) return null;
+
+      // Get a matching tip
+      const tip = tipEngine.getTip(context);
+
+      if (tip && !permanentlyDismissed.has(tip.id)) {
+        setCurrentTip(tip);
+        setTipVisible(true);
+        setTipsShownCount((prev) => prev + 1);
+        setLastTipTime(now);
+        onTipShown?.(tip);
+        return tip;
+      }
+
+      return null;
+    },
+    [
+      tipsEnabled,
+      tipsShownCount,
+      lastTipTime,
+      tipEngine,
+      permanentlyDismissed,
+      config.maxTipsPerSession,
+      config.tipIntervalMs,
+      onTipShown,
+    ]
+  );
+
+  // Dismiss current tip
+  const dismissTip = useCallback(() => {
+    if (currentTip) {
+      onTipDismissed?.(currentTip.id);
+    }
+    setCurrentTip(null);
+    setTipVisible(false);
+  }, [currentTip, onTipDismissed]);
+
+  // Permanently dismiss a tip
+  const dismissTipPermanently = useCallback(
+    (tipId: string) => {
+      setPermanentlyDismissed((prev) => new Set([...prev, tipId]));
+      tipEngine.dismissTip(tipId);
+      if (currentTip?.id === tipId) {
+        dismissTip();
+      }
+    },
+    [tipEngine, currentTip, dismissTip]
+  );
+
+  // Get a specific tip
+  const getTip = useCallback(
+    (tipId: string): Tip | undefined => {
+      return tipEngine.getAllTips().find((t) => t.id === tipId);
+    },
+    [tipEngine]
+  );
+
+  // Check if a tip has been shown
+  const hasTipBeenShown = useCallback(
+    (tipId: string): boolean => {
+      const state = tipEngine.getTipState(tipId);
+      return state?.showCount !== undefined && state.showCount > 0;
+    },
+    [tipEngine]
+  );
+
+  // Reset tips (for testing)
+  const resetTips = useCallback(() => {
+    tipEngine.resetAllStates();
+    setCurrentTip(null);
+    setTipVisible(false);
+    setTipsShownCount(0);
+    setPermanentlyDismissed(new Set());
+  }, [tipEngine]);
+
+  return {
+    // State
+    currentTip,
+    tipsEnabled,
+    tipsShownCount,
+    tipVisible,
+    // Actions
+    showTip,
+    dismissTip,
+    dismissTipPermanently,
+    setTipsEnabled,
+    getTip,
+    hasTipBeenShown,
+    resetTips,
+  };
+}
+
+// =============================================================================
+// Context Builders
+// =============================================================================
+
+/**
+ * Build a tip context from application state.
+ *
+ * @param options - Context building options
+ * @returns TipContext for tip matching
+ *
+ * @example
+ * ```typescript
+ * const context = buildTipContext({
+ *   screen: "main",
+ *   mode: "vibe",
+ *   command: "/help",
+ *   featuresUsedCount: 10,
+ * });
+ * const tip = tipEngine.getTip(context);
+ * ```
+ */
+export function buildTipContext(options: {
+  screen?: string;
+  mode?: string;
+  command?: string;
+  featuresUsedCount?: number;
+  sessionDuration?: number;
+  hasError?: boolean;
+  experienceLevel?: "new" | "beginner" | "intermediate" | "advanced";
+  custom?: Record<string, unknown>;
+}): TipContext {
+  return {
+    screen: options.screen ?? "main",
+    mode: options.mode,
+    command: options.command,
+    featuresUsedCount: options.featuresUsedCount ?? 0,
+    sessionDuration: options.sessionDuration,
+    hasError: options.hasError,
+    experienceLevel: options.experienceLevel ?? "new",
+    custom: options.custom,
+  };
+}
+
+/**
+ * Get tips relevant to a specific feature or command.
+ *
+ * @param tipEngine - TipEngine instance
+ * @param feature - Feature or command name
+ * @returns Relevant tips
+ */
+export function getTipsForFeature(tipEngine: TipEngine, feature: string): Tip[] {
+  const allTips = tipEngine.getAllTips();
+  return allTips.filter(
+    (tip) =>
+      tip.trigger.commands?.includes(feature) ||
+      tip.relatedLessonId === feature ||
+      tip.content.toLowerCase().includes(feature.toLowerCase())
+  );
+}
+
+// =============================================================================
+// Exports
+// =============================================================================
+
+export { BUILTIN_TIPS, createTipEngine, TipEngine, type Tip, type TipContext, type TipState };

package/src/tui/types/__tests__/ink-extended.test.ts

@@ -0,0 +1,121 @@
+/**
+ * Tests for Extended Ink Key Utilities
+ */
+import type { Key } from "ink";
+import { describe, expect, it } from "vitest";
+import { type ExtendedKey, extendKey, isEndKey, isHomeKey } from "../ink-extended.js";
+
+describe("ink-extended", () => {
+  // Base key object for testing
+  const baseKey: Key = {
+    upArrow: false,
+    downArrow: false,
+    leftArrow: false,
+    rightArrow: false,
+    pageDown: false,
+    pageUp: false,
+    return: false,
+    escape: false,
+    ctrl: false,
+    shift: false,
+    tab: false,
+    backspace: false,
+    delete: false,
+    meta: false,
+  };
+
+  describe("extendKey", () => {
+    it("extends key object with home and end properties", () => {
+      const result = extendKey("a", baseKey);
+      expect(result).toHaveProperty("home");
+      expect(result).toHaveProperty("end");
+    });
+
+    it("preserves original key properties", () => {
+      const key: Key = { ...baseKey, ctrl: true, shift: true };
+      const result = extendKey("a", key);
+      expect(result.ctrl).toBe(true);
+      expect(result.shift).toBe(true);
+    });
+
+    it("detects Home key (CSI H)", () => {
+      const result = extendKey("\x1b[H", baseKey);
+      expect(result.home).toBe(true);
+      expect(result.end).toBe(false);
+    });
+
+    it("detects Home key (CSI 1 ~)", () => {
+      const result = extendKey("\x1b[1~", baseKey);
+      expect(result.home).toBe(true);
+    });
+
+    it("detects Home key (SS3 H)", () => {
+      const result = extendKey("\x1bOH", baseKey);
+      expect(result.home).toBe(true);
+    });
+
+    it("detects End key (CSI F)", () => {
+      const result = extendKey("\x1b[F", baseKey);
+      expect(result.end).toBe(true);
+      expect(result.home).toBe(false);
+    });
+
+    it("detects End key (CSI 4 ~)", () => {
+      const result = extendKey("\x1b[4~", baseKey);
+      expect(result.end).toBe(true);
+    });
+
+    it("detects End key (SS3 F)", () => {
+      const result = extendKey("\x1bOF", baseKey);
+      expect(result.end).toBe(true);
+    });
+
+    it("returns false for both when regular input", () => {
+      const result = extendKey("a", baseKey);
+      expect(result.home).toBe(false);
+      expect(result.end).toBe(false);
+    });
+
+    it("returns false for both on empty string", () => {
+      const result = extendKey("", baseKey);
+      expect(result.home).toBe(false);
+      expect(result.end).toBe(false);
+    });
+  });
+
+  describe("isHomeKey", () => {
+    it("returns true for Home sequences", () => {
+      expect(isHomeKey("\x1b[H")).toBe(true);
+      expect(isHomeKey("\x1b[1~")).toBe(true);
+      expect(isHomeKey("\x1bOH")).toBe(true);
+    });
+
+    it("returns false for non-Home input", () => {
+      expect(isHomeKey("a")).toBe(false);
+      expect(isHomeKey("\x1b[F")).toBe(false); // End key
+      expect(isHomeKey("")).toBe(false);
+    });
+  });
+
+  describe("isEndKey", () => {
+    it("returns true for End sequences", () => {
+      expect(isEndKey("\x1b[F")).toBe(true);
+      expect(isEndKey("\x1b[4~")).toBe(true);
+      expect(isEndKey("\x1bOF")).toBe(true);
+    });
+
+    it("returns false for non-End input", () => {
+      expect(isEndKey("a")).toBe(false);
+      expect(isEndKey("\x1b[H")).toBe(false); // Home key
+      expect(isEndKey("")).toBe(false);
+    });
+  });
+
+  describe("ExtendedKey type", () => {
+    it("is assignable from extendKey result", () => {
+      const result: ExtendedKey = extendKey("a", baseKey);
+      expect(result.home).toBeDefined();
+      expect(result.end).toBeDefined();
+    });
+  });
+});

package/src/tui/types/ink-extended.ts

@@ -0,0 +1,87 @@
+/**
+ * Extended Key type for ink's useInput hook.
+ *
+ * The @jrichman/ink fork (and some versions of ink) don't include `home` and `end`
+ * properties in the Key type. This module provides an extended type and helper
+ * function to detect these keys from raw input.
+ *
+ * @module ink-extended
+ */
+
+import type { Key } from "ink";
+
+/**
+ * Extended Key type that includes home and end key detection.
+ * These are not present in the base ink Key type but are commonly needed
+ * for navigation in TUI applications.
+ */
+export interface ExtendedKey extends Key {
+  /** Home key was pressed (jump to beginning) */
+  home: boolean;
+  /** End key was pressed (jump to end) */
+  end: boolean;
+}
+
+/**
+ * ANSI escape sequences for Home and End keys.
+ * Different terminal emulators may send different sequences.
+ */
+const HOME_SEQUENCES = [
+  "\x1b[H", // CSI H
+  "\x1b[1~", // CSI 1 ~
+  "\x1bOH", // SS3 H (application mode)
+];
+
+const END_SEQUENCES = [
+  "\x1b[F", // CSI F
+  "\x1b[4~", // CSI 4 ~
+  "\x1bOF", // SS3 F (application mode)
+];
+
+/**
+ * Extends the ink Key object with home and end key detection.
+ * Call this with the raw input string and the key object from useInput.
+ *
+ * @param input - The raw input string from useInput
+ * @param key - The Key object from useInput
+ * @returns Extended key object with home and end properties
+ *
+ * @example
+ * ```tsx
+ * import { useInput } from 'ink';
+ * import { extendKey } from '../types/ink-extended';
+ *
+ * useInput((input, key) => {
+ *   const extKey = extendKey(input, key);
+ *   if (extKey.home) {
+ *     // Handle Home key
+ *   }
+ *   if (extKey.end) {
+ *     // Handle End key
+ *   }
+ * });
+ * ```
+ */
+export function extendKey(input: string, key: Key): ExtendedKey {
+  return {
+    ...key,
+    home: HOME_SEQUENCES.includes(input),
+    end: END_SEQUENCES.includes(input),
+  };
+}
+
+/**
+ * Check if the input represents a Home key press.
+ * Use this for simple boolean checks without needing the full extended key.
+ */
+export function isHomeKey(input: string): boolean {
+  return HOME_SEQUENCES.includes(input);
+}
+
+/**
+ * Check if the input represents an End key press.
+ * Use this for simple boolean checks without needing the full extended key.
+ */
+export function isEndKey(input: string): boolean {
+  return END_SEQUENCES.includes(input);
+}