cli-menu-kit 0.1.26 → 0.2.0

package/dist/core/hint-manager.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Hint Manager - Manages hints from multiple components with priority
+ *
+ * Allows multiple components to set hints with different priorities.
+ * The highest priority hint is displayed.
+ */
+import { EventEmitter } from 'events';
+export declare class HintManager extends EventEmitter {
+    private entries;
+    /**
+     * Set a hint with a token and priority
+     * @param token - Unique identifier for this hint source
+     * @param text - Hint text to display
+     * @param priority - Higher priority hints are displayed first (default: 0)
+     */
+    set(token: string, text: string, priority?: number): void;
+    /**
+     * Clear a hint by token
+     */
+    clear(token: string): void;
+    /**
+     * Get the current highest priority hint
+     */
+    current(): string;
+    /**
+     * Clear all hints
+     */
+    clearAll(): void;
+}

package/dist/core/hint-manager.js

@@ -0,0 +1,65 @@
+"use strict";
+/**
+ * Hint Manager - Manages hints from multiple components with priority
+ *
+ * Allows multiple components to set hints with different priorities.
+ * The highest priority hint is displayed.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HintManager = void 0;
+const events_1 = require("events");
+class HintManager extends events_1.EventEmitter {
+    constructor() {
+        super(...arguments);
+        this.entries = new Map();
+    }
+    /**
+     * Set a hint with a token and priority
+     * @param token - Unique identifier for this hint source
+     * @param text - Hint text to display
+     * @param priority - Higher priority hints are displayed first (default: 0)
+     */
+    set(token, text, priority = 0) {
+        this.entries.set(token, {
+            text,
+            priority,
+            timestamp: Date.now()
+        });
+        this.emit('change', this.current());
+    }
+    /**
+     * Clear a hint by token
+     */
+    clear(token) {
+        if (this.entries.delete(token)) {
+            this.emit('change', this.current());
+        }
+    }
+    /**
+     * Get the current highest priority hint
+     */
+    current() {
+        const list = Array.from(this.entries.values());
+        if (list.length === 0) {
+            return '';
+        }
+        // Sort by priority (descending), then by timestamp (most recent first)
+        list.sort((a, b) => {
+            if (b.priority !== a.priority) {
+                return b.priority - a.priority;
+            }
+            return b.timestamp - a.timestamp;
+        });
+        return list[0].text;
+    }
+    /**
+     * Clear all hints
+     */
+    clearAll() {
+        if (this.entries.size > 0) {
+            this.entries.clear();
+            this.emit('change', '');
+        }
+    }
+}
+exports.HintManager = HintManager;

package/dist/core/renderer.d.ts

@@ -43,8 +43,9 @@ export declare function renderSeparator(char?: string, width?: number): void;
  * Render a section label (menu grouping)
  * @param label - Label text (optional)
  * @param width - Total width of the separator (default: 30)
+ * @param align - Alignment of the label (default: 'center')
  */
-export declare function renderSectionLabel(label?: string, width?: number): void;
+export declare function renderSectionLabel(label?: string, width?: number, align?: 'left' | 'center' | 'right'): void;
 /**
  * Render a message with icon
  * @param type - Message type (success, error, warning, info, question)

package/dist/core/renderer.js

@@ -135,17 +135,33 @@ function renderSeparator(char = '─', width) {
  * Render a section label (menu grouping)
  * @param label - Label text (optional)
  * @param width - Total width of the separator (default: 30)
+ * @param align - Alignment of the label (default: 'center')
  */
-function renderSectionLabel(label, width = 30) {
+function renderSectionLabel(label, width = 30, align = 'center') {
     if (label) {
-        const totalWidth = width; // Use configured width
-        const padding = 2; // Spaces around label
+        const totalWidth = width;
         const labelWithPadding = ` ${label} `;
         const labelLength = labelWithPadding.length;
         const dashesTotal = totalWidth - labelLength;
-        const dashesLeft = Math.floor(dashesTotal / 2);
-        const dashesRight = dashesTotal - dashesLeft;
-        const line = `  ${colors_js_1.uiColors.separator}${'─'.repeat(dashesLeft)}${labelWithPadding}${'─'.repeat(dashesRight)}${colors_js_1.colors.reset}`;
+        let dashesLeft;
+        let dashesRight;
+        switch (align) {
+            case 'left':
+                dashesLeft = 0;
+                dashesRight = dashesTotal;
+                break;
+            case 'right':
+                dashesLeft = dashesTotal;
+                dashesRight = 0;
+                break;
+            case 'center':
+            default:
+                dashesLeft = Math.floor(dashesTotal / 2);
+                dashesRight = dashesTotal - dashesLeft;
+                break;
+        }
+        // Use primary color (cyan) and bold for phase labels
+        const line = `  ${colors_js_1.colors.cyan}${colors_js_1.colors.bold}${'─'.repeat(dashesLeft)}${labelWithPadding}${'─'.repeat(dashesRight)}${colors_js_1.colors.reset}`;
         (0, terminal_js_1.writeLine)(line);
     }
     else {

package/dist/core/screen-manager.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Screen Manager - Manages screen regions with fixed-height layout
+ *
+ * Uses absolute cursor positioning and per-region caching for efficient updates.
+ * Only updates regions that have changed (diff-based rendering).
+ */
+export interface Rect {
+    top: number;
+    left: number;
+    width: number;
+    height: number;
+}
+export declare class ScreenManager {
+    private cache;
+    private regions;
+    private isAltScreen;
+    /**
+     * Enter alternate screen buffer and hide cursor
+     */
+    enter(): void;
+    /**
+     * Exit alternate screen buffer and show cursor
+     */
+    exit(): void;
+    /**
+     * Move cursor to absolute position (1-based)
+     */
+    moveTo(row: number, col: number): void;
+    /**
+     * Register a fixed-height region
+     */
+    registerRegion(id: string, rect: Rect): void;
+    /**
+     * Render a region with diff-based updates
+     * Only updates lines that have changed
+     */
+    renderRegion(id: string, lines: string[]): void;
+    /**
+     * Clear a region (fill with spaces)
+     */
+    clearRegion(id: string): void;
+    /**
+     * Invalidate all cached content (forces full re-render on next update)
+     */
+    invalidateAll(): void;
+    /**
+     * Reset manager state
+     */
+    reset(): void;
+    /**
+     * Get region rect
+     */
+    getRegion(id: string): Rect | undefined;
+}

package/dist/core/screen-manager.js

@@ -0,0 +1,119 @@
+"use strict";
+/**
+ * Screen Manager - Manages screen regions with fixed-height layout
+ *
+ * Uses absolute cursor positioning and per-region caching for efficient updates.
+ * Only updates regions that have changed (diff-based rendering).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScreenManager = void 0;
+const CSI = '\x1b[';
+/**
+ * Fit text to exact width by padding or truncating
+ */
+function fitText(text, width) {
+    // Simple implementation - can be enhanced with ANSI-aware width calculation
+    const stripped = text.replace(/\x1b\[[0-9;]*m/g, ''); // Strip ANSI codes for length calc
+    const len = stripped.length;
+    if (len === width)
+        return text;
+    if (len < width)
+        return text + ' '.repeat(width - len);
+    // Truncate - preserve ANSI codes at start if present
+    const ansiMatch = text.match(/^(\x1b\[[0-9;]*m)*/);
+    const prefix = ansiMatch ? ansiMatch[0] : '';
+    const content = text.slice(prefix.length);
+    return prefix + content.slice(0, width);
+}
+class ScreenManager {
+    constructor() {
+        this.cache = new Map();
+        this.regions = new Map();
+        this.isAltScreen = false;
+    }
+    /**
+     * Enter alternate screen buffer and hide cursor
+     */
+    enter() {
+        if (!this.isAltScreen) {
+            process.stdout.write(`${CSI}?1049h${CSI}?25l`);
+            this.isAltScreen = true;
+        }
+    }
+    /**
+     * Exit alternate screen buffer and show cursor
+     */
+    exit() {
+        if (this.isAltScreen) {
+            process.stdout.write(`${CSI}?25h${CSI}?1049l`);
+            this.isAltScreen = false;
+        }
+    }
+    /**
+     * Move cursor to absolute position (1-based)
+     */
+    moveTo(row, col) {
+        process.stdout.write(`${CSI}${row};${col}H`);
+    }
+    /**
+     * Register a fixed-height region
+     */
+    registerRegion(id, rect) {
+        this.regions.set(id, rect);
+    }
+    /**
+     * Render a region with diff-based updates
+     * Only updates lines that have changed
+     */
+    renderRegion(id, lines) {
+        const rect = this.regions.get(id);
+        if (!rect) {
+            throw new Error(`Region ${id} not registered`);
+        }
+        const prev = this.cache.get(id) ?? [];
+        const next = Array.from({ length: rect.height }, (_, i) => fitText(lines[i] ?? '', rect.width));
+        // Update only changed lines
+        for (let i = 0; i < rect.height; i++) {
+            if (next[i] === prev[i])
+                continue;
+            this.moveTo(rect.top + i, rect.left);
+            process.stdout.write(next[i]);
+        }
+        this.cache.set(id, next);
+    }
+    /**
+     * Clear a region (fill with spaces)
+     */
+    clearRegion(id) {
+        const rect = this.regions.get(id);
+        if (!rect) {
+            throw new Error(`Region ${id} not registered`);
+        }
+        const blank = ' '.repeat(rect.width);
+        for (let i = 0; i < rect.height; i++) {
+            this.moveTo(rect.top + i, rect.left);
+            process.stdout.write(blank);
+        }
+        this.cache.set(id, Array(rect.height).fill(blank));
+    }
+    /**
+     * Invalidate all cached content (forces full re-render on next update)
+     */
+    invalidateAll() {
+        this.cache.clear();
+    }
+    /**
+     * Reset manager state
+     */
+    reset() {
+        this.cache.clear();
+        this.regions.clear();
+    }
+    /**
+     * Get region rect
+     */
+    getRegion(id) {
+        return this.regions.get(id);
+    }
+}
+exports.ScreenManager = ScreenManager;

package/dist/core/state-manager.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared State Manager
+ * Allows components to share state without direct coupling
+ */
+type StateListener<T> = (value: T) => void;
+export declare class StateManager {
+    private states;
+    private listeners;
+    /**
+     * Set a state value and notify listeners
+     */
+    setState<T>(key: string, value: T): void;
+    /**
+     * Get a state value
+     */
+    getState<T>(key: string): T | undefined;
+    /**
+     * Subscribe to state changes
+     */
+    subscribe<T>(key: string, listener: StateListener<T>): () => void;
+    /**
+     * Clear all state
+     */
+    clear(): void;
+}
+export declare const globalState: StateManager;
+export {};

package/dist/core/state-manager.js

@@ -0,0 +1,56 @@
+"use strict";
+/**
+ * Shared State Manager
+ * Allows components to share state without direct coupling
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.globalState = exports.StateManager = void 0;
+class StateManager {
+    constructor() {
+        this.states = new Map();
+        this.listeners = new Map();
+    }
+    /**
+     * Set a state value and notify listeners
+     */
+    setState(key, value) {
+        this.states.set(key, value);
+        // Notify all listeners
+        const listeners = this.listeners.get(key);
+        if (listeners) {
+            listeners.forEach(listener => listener(value));
+        }
+    }
+    /**
+     * Get a state value
+     */
+    getState(key) {
+        return this.states.get(key);
+    }
+    /**
+     * Subscribe to state changes
+     */
+    subscribe(key, listener) {
+        if (!this.listeners.has(key)) {
+            this.listeners.set(key, new Set());
+        }
+        this.listeners.get(key).add(listener);
+        // Return unsubscribe function
+        return () => {
+            const listeners = this.listeners.get(key);
+            if (listeners) {
+                listeners.delete(listener);
+            }
+        };
+    }
+    /**
+     * Clear all state
+     */
+    clear() {
+        this.states.clear();
+        this.listeners.clear();
+    }
+}
+exports.StateManager = StateManager;
+// Global state manager instance
+exports.globalState = new StateManager();

package/dist/core/terminal.d.ts

@@ -9,12 +9,14 @@ export interface TerminalState {
     stdin: NodeJS.ReadStream;
     renderedLines: number;
     isRawMode: boolean;
+    useAltScreen: boolean;
 }
 /**
  * Initialize terminal for interactive mode
+ * @param useAltScreen - Whether to use alternate screen buffer (prevents scroll issues)
  * @returns Terminal state object
  */
-export declare function initTerminal(): TerminalState;
+export declare function initTerminal(useAltScreen?: boolean): TerminalState;
 /**
  * Restore terminal to normal mode
  * @param state - Terminal state
@@ -22,6 +24,7 @@ export declare function initTerminal(): TerminalState;
 export declare function restoreTerminal(state: TerminalState): void;
 /**
  * Clear the current menu display
+ * Only clears the lines that were rendered by this menu
  * @param state - Terminal state
  */
 export declare function clearMenu(state: TerminalState): void;

package/dist/core/terminal.js

@@ -22,20 +22,36 @@ exports.clearScreen = clearScreen;
 exports.exitWithGoodbye = exitWithGoodbye;
 /**
  * Initialize terminal for interactive mode
+ * @param useAltScreen - Whether to use alternate screen buffer (prevents scroll issues)
  * @returns Terminal state object
  */
-function initTerminal() {
+function initTerminal(useAltScreen = false) {
     const stdin = process.stdin;
+    // Disable all mouse tracking modes BEFORE enabling raw mode
+    process.stdout.write('\x1b[?1000l'); // Disable normal mouse tracking
+    process.stdout.write('\x1b[?1001l'); // Disable highlight mouse tracking
+    process.stdout.write('\x1b[?1002l'); // Disable button event tracking
+    process.stdout.write('\x1b[?1003l'); // Disable any event tracking
+    process.stdout.write('\x1b[?1004l'); // Disable focus events
+    process.stdout.write('\x1b[?1005l'); // Disable UTF-8 mouse mode
+    process.stdout.write('\x1b[?1006l'); // Disable SGR extended mouse mode
+    process.stdout.write('\x1b[?1015l'); // Disable urxvt mouse mode
     // Enable raw mode for character-by-character input
     stdin.setRawMode(true);
     stdin.resume();
     stdin.setEncoding('utf8');
+    // Use alternate screen buffer if requested
+    if (useAltScreen) {
+        process.stdout.write('\x1b[?1049h'); // Enable alternate screen
+        process.stdout.write('\x1b[H'); // Move cursor to home
+    }
     // Hide cursor
     process.stdout.write('\x1b[?25l');
     return {
         stdin,
         renderedLines: 0,
-        isRawMode: true
+        isRawMode: true,
+        useAltScreen
     };
 }
 /**
@@ -47,20 +63,37 @@ function restoreTerminal(state) {
         state.stdin.setRawMode(false);
         state.isRawMode = false;
     }
+    // Restore alternate screen if it was used
+    if (state.useAltScreen) {
+        process.stdout.write('\x1b[?1049l'); // Disable alternate screen
+    }
     // Show cursor
     process.stdout.write('\x1b[?25h');
     state.stdin.pause();
 }
 /**
  * Clear the current menu display
+ * Only clears the lines that were rendered by this menu
  * @param state - Terminal state
  */
 function clearMenu(state) {
     if (state.renderedLines > 0) {
         // Move cursor up to the start of the menu
         process.stdout.write(`\x1b[${state.renderedLines}A`);
-        // Clear from cursor to end of screen
-        process.stdout.write('\x1b[J');
+        // Clear each line individually
+        for (let i = 0; i < state.renderedLines; i++) {
+            process.stdout.write('\x1b[2K'); // Clear entire line
+            if (i < state.renderedLines - 1) {
+                process.stdout.write('\x1b[1B'); // Move down one line
+            }
+        }
+        // Move cursor back to start position
+        // After loop, cursor is at the last rendered line
+        // To get back to line 1, move up (renderedLines - 1)
+        // Note: \x1b[0A defaults to 1 in ANSI spec, so skip when renderedLines === 1
+        if (state.renderedLines > 1) {
+            process.stdout.write(`\x1b[${state.renderedLines - 1}A`);
+        }
         state.renderedLines = 0;
     }
 }

package/dist/core/virtual-scroll.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Virtual scrolling utilities for rendering large lists efficiently
+ * by only displaying a visible window of items.
+ */
+export interface VirtualScrollOptions<T> {
+    /** All items in the list */
+    items: T[];
+    /** Current cursor/focus position (index in items array) */
+    cursorIndex: number;
+    /** Target number of lines to display */
+    targetLines: number;
+    /** Function to calculate how many lines each item will occupy when rendered */
+    getItemLineCount: (item: T, index: number) => number;
+}
+export interface VirtualScrollResult {
+    /** Start index of visible range (inclusive) */
+    visibleStart: number;
+    /** End index of visible range (exclusive) */
+    visibleEnd: number;
+    /** Actual number of lines that will be rendered */
+    actualLines: number;
+    /** Whether virtual scrolling is active (content exceeds target) */
+    isScrolled: boolean;
+    /** Whether there are items before the visible range */
+    hasItemsBefore: boolean;
+    /** Whether there are items after the visible range */
+    hasItemsAfter: boolean;
+}
+/**
+ * Calculate visible range for virtual scrolling based on line count.
+ *
+ * This function maintains a stable viewport height by calculating which items
+ * to display based on their actual line count, not just item count. This prevents
+ * height jumping when items have varying heights (e.g., separators with descriptions).
+ *
+ * Algorithm:
+ * 1. Calculate total lines needed for all items
+ * 2. If total <= targetLines, show everything (no scrolling)
+ * 3. Otherwise, create a window centered on cursor:
+ *    - Start from cursor position
+ *    - Expand downward until reaching target or end
+ *    - Expand upward to fill remaining space
+ *    - Expand downward again if space remains
+ *
+ * @example
+ * ```typescript
+ * const result = calculateVirtualScroll({
+ *   items: menuOptions,
+ *   cursorIndex: 10,
+ *   targetLines: 30,
+ *   getItemLineCount: (item, index) => {
+ *     if (item.type === 'separator') {
+ *       return 1 + (item.description ? 1 : 0) + (index > 0 ? 1 : 0);
+ *     }
+ *     return 1;
+ *   }
+ * });
+ *
+ * // Render only visible items
+ * for (let i = result.visibleStart; i < result.visibleEnd; i++) {
+ *   renderItem(items[i]);
+ * }
+ * ```
+ */
+export declare function calculateVirtualScroll<T>(options: VirtualScrollOptions<T>): VirtualScrollResult;