cli-menu-kit 0.1.26 → 0.2.1

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,27 @@ export interface TerminalState {
     stdin: NodeJS.ReadStream;
     renderedLines: number;
     isRawMode: boolean;
+    useAltScreen: boolean;
 }
+/**
+ * Remove ANSI escape sequences from a string.
+ * This is required when calculating the visible width in terminal cells.
+ */
+export declare function stripAnsi(text: string): string;
+/**
+ * Calculate the visible width of a string in terminal cells.
+ */
+export declare function getDisplayWidth(text: string): number;
+/**
+ * Count how many visual rows the text occupies after terminal wrapping.
+ */
+export declare function countVisualLines(text: string, terminalWidth?: number): number;
 /**
  * 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 +37,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

@@ -4,6 +4,9 @@
  * Handles cursor movement, screen clearing, and terminal state
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.stripAnsi = stripAnsi;
+exports.getDisplayWidth = getDisplayWidth;
+exports.countVisualLines = countVisualLines;
 exports.initTerminal = initTerminal;
 exports.restoreTerminal = restoreTerminal;
 exports.clearMenu = clearMenu;
@@ -20,22 +23,122 @@ exports.getTerminalWidth = getTerminalWidth;
 exports.getTerminalHeight = getTerminalHeight;
 exports.clearScreen = clearScreen;
 exports.exitWithGoodbye = exitWithGoodbye;
+const ANSI_ESCAPE_PATTERN = /[\u001B\u009B][[\]()#;?]*(?:(?:[a-zA-Z\d]*(?:;[a-zA-Z\d]*)*)?\u0007|(?:\d{1,4}(?:;\d{0,4})*)?[\dA-PR-TZcf-nq-uy=><~])/g;
+const TAB_WIDTH = 4;
+/**
+ * Remove ANSI escape sequences from a string.
+ * This is required when calculating the visible width in terminal cells.
+ */
+function stripAnsi(text) {
+    return text.replace(ANSI_ESCAPE_PATTERN, '');
+}
+function isCombiningCodePoint(codePoint) {
+    return ((codePoint >= 0x0300 && codePoint <= 0x036F) || // Combining Diacritical Marks
+        (codePoint >= 0x1AB0 && codePoint <= 0x1AFF) || // Combining Diacritical Marks Extended
+        (codePoint >= 0x1DC0 && codePoint <= 0x1DFF) || // Combining Diacritical Marks Supplement
+        (codePoint >= 0x20D0 && codePoint <= 0x20FF) || // Combining Diacritical Marks for Symbols
+        (codePoint >= 0xFE20 && codePoint <= 0xFE2F) // Combining Half Marks
+    );
+}
+function isFullWidthCodePoint(codePoint) {
+    if (codePoint < 0x1100) {
+        return false;
+    }
+    return (codePoint <= 0x115F ||
+        codePoint === 0x2329 ||
+        codePoint === 0x232A ||
+        ((codePoint >= 0x2E80 && codePoint <= 0x3247) && codePoint !== 0x303F) ||
+        (codePoint >= 0x3250 && codePoint <= 0x4DBF) ||
+        (codePoint >= 0x4E00 && codePoint <= 0xA4C6) ||
+        (codePoint >= 0xA960 && codePoint <= 0xA97C) ||
+        (codePoint >= 0xAC00 && codePoint <= 0xD7A3) ||
+        (codePoint >= 0xF900 && codePoint <= 0xFAFF) ||
+        (codePoint >= 0xFE10 && codePoint <= 0xFE19) ||
+        (codePoint >= 0xFE30 && codePoint <= 0xFE6B) ||
+        (codePoint >= 0xFF01 && codePoint <= 0xFF60) ||
+        (codePoint >= 0xFFE0 && codePoint <= 0xFFE6) ||
+        (codePoint >= 0x1B000 && codePoint <= 0x1B001) ||
+        (codePoint >= 0x1F200 && codePoint <= 0x1F251) ||
+        (codePoint >= 0x20000 && codePoint <= 0x3FFFD));
+}
+function getCharacterWidth(char, currentLineWidth) {
+    if (char === '\t') {
+        const remainder = currentLineWidth % TAB_WIDTH;
+        return remainder === 0 ? TAB_WIDTH : TAB_WIDTH - remainder;
+    }
+    const codePoint = char.codePointAt(0);
+    if (codePoint === undefined) {
+        return 0;
+    }
+    // Control characters and zero-width joiners/modifiers.
+    if (codePoint <= 0x001F ||
+        (codePoint >= 0x007F && codePoint <= 0x009F) ||
+        codePoint === 0x200D ||
+        (codePoint >= 0xFE00 && codePoint <= 0xFE0F) ||
+        isCombiningCodePoint(codePoint)) {
+        return 0;
+    }
+    if (isFullWidthCodePoint(codePoint) || (codePoint >= 0x1F300 && codePoint <= 0x1FAFF)) {
+        return 2;
+    }
+    return 1;
+}
+/**
+ * Calculate the visible width of a string in terminal cells.
+ */
+function getDisplayWidth(text) {
+    const plain = stripAnsi(text);
+    let width = 0;
+    for (const char of plain) {
+        width += getCharacterWidth(char, width);
+    }
+    return width;
+}
+/**
+ * Count how many visual rows the text occupies after terminal wrapping.
+ */
+function countVisualLines(text, terminalWidth = getTerminalWidth()) {
+    const width = Math.max(1, terminalWidth);
+    const lines = text.split(/\r\n|\r|\n/);
+    let lineCount = 0;
+    for (const line of lines) {
+        const visualWidth = getDisplayWidth(line);
+        lineCount += Math.max(1, Math.ceil(visualWidth / width));
+    }
+    return lineCount;
+}
 /**
  * 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 +150,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;

package/dist/core/virtual-scroll.js

@@ -0,0 +1,120 @@
+"use strict";
+/**
+ * Virtual scrolling utilities for rendering large lists efficiently
+ * by only displaying a visible window of items.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculateVirtualScroll = calculateVirtualScroll;
+/**
+ * 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]);
+ * }
+ * ```
+ */
+function calculateVirtualScroll(options) {
+    const { items, cursorIndex, targetLines, getItemLineCount } = options;
+    // Validate inputs
+    if (items.length === 0) {
+        return {
+            visibleStart: 0,
+            visibleEnd: 0,
+            actualLines: 0,
+            isScrolled: false,
+            hasItemsBefore: false,
+            hasItemsAfter: false
+        };
+    }
+    if (cursorIndex < 0 || cursorIndex >= items.length) {
+        throw new Error(`cursorIndex ${cursorIndex} is out of bounds [0, ${items.length})`);
+    }
+    // Calculate total lines for all items
+    const estimatedTotalLines = items.reduce((sum, item, idx) => {
+        return sum + getItemLineCount(item, idx);
+    }, 0);
+    // If content fits within target, show everything
+    if (estimatedTotalLines <= targetLines) {
+        return {
+            visibleStart: 0,
+            visibleEnd: items.length,
+            actualLines: estimatedTotalLines,
+            isScrolled: false,
+            hasItemsBefore: false,
+            hasItemsAfter: false
+        };
+    }
+    // Virtual scrolling: maintain constant line count
+    let visibleStart = cursorIndex;
+    let visibleEnd = cursorIndex + 1;
+    let currentLines = getItemLineCount(items[cursorIndex], cursorIndex);
+    // Phase 1: Expand downward from cursor
+    while (visibleEnd < items.length && currentLines < targetLines) {
+        const nextLines = getItemLineCount(items[visibleEnd], visibleEnd);
+        if (currentLines + nextLines <= targetLines) {
+            currentLines += nextLines;
+            visibleEnd++;
+        }
+        else {
+            break;
+        }
+    }
+    // Phase 2: Expand upward to fill remaining space
+    while (visibleStart > 0 && currentLines < targetLines) {
+        const prevLines = getItemLineCount(items[visibleStart - 1], visibleStart - 1);
+        if (currentLines + prevLines <= targetLines) {
+            visibleStart--;
+            currentLines += prevLines;
+        }
+        else {
+            break;
+        }
+    }
+    // Phase 3: Try expanding downward again if space remains
+    while (visibleEnd < items.length && currentLines < targetLines) {
+        const nextLines = getItemLineCount(items[visibleEnd], visibleEnd);
+        if (currentLines + nextLines <= targetLines) {
+            currentLines += nextLines;
+            visibleEnd++;
+        }
+        else {
+            break;
+        }
+    }
+    return {
+        visibleStart,
+        visibleEnd,
+        actualLines: currentLines,
+        isScrolled: true,
+        hasItemsBefore: visibleStart > 0,
+        hasItemsAfter: visibleEnd < items.length
+    };
+}