@compilr-dev/cli 0.4.0 → 0.5.1

package/dist/ui/base/screen-stack.js

@@ -0,0 +1,184 @@
+/**
+ * Screen Stack
+ *
+ * Navigation stack for multi-screen overlays.
+ * Enables proper "back" behavior where Esc goes to previous screen.
+ *
+ * Usage:
+ * ```typescript
+ * class MyOverlay extends BaseOverlay<MyState, MyResult> {
+ *   private screenStack = new ScreenStack();
+ *
+ *   constructor() {
+ *     super(initialState);
+ *     this.screenStack.push(new ListScreen());
+ *   }
+ *
+ *   handleKey(data: Buffer): void {
+ *     if (isEscape(data)) {
+ *       if (this.screenStack.size() > 1) {
+ *         this.screenStack.pop();
+ *         this.update();
+ *       } else {
+ *         this.close(null);
+ *       }
+ *       return;
+ *     }
+ *
+ *     const result = this.screenStack.current()?.handleKey(data);
+ *     this.handleScreenResult(result);
+ *   }
+ *
+ *   render(): string[] {
+ *     return [
+ *       ...this.renderHeader('My Overlay'),
+ *       ...this.screenStack.current()?.render() ?? [],
+ *       ...this.renderFooter(this.getCurrentHints())
+ *     ];
+ *   }
+ * }
+ * ```
+ */
+// =============================================================================
+// BaseScreen Abstract Class
+// =============================================================================
+/**
+ * Abstract base class for screens.
+ * Extend this to create screens for multi-screen overlays.
+ */
+export class BaseScreen {
+    /**
+     * Optional: Return minimum height for stable rendering.
+     * Override to prevent visual jitter when screen content varies.
+     * @returns Minimum number of lines this screen should occupy
+     */
+    getMinHeight() {
+        return 0; // Default: no minimum, use overlay's minHeight
+    }
+}
+// =============================================================================
+// ScreenStack Class
+// =============================================================================
+/**
+ * Stack-based navigation for multi-screen overlays.
+ *
+ * The stack maintains a history of screens, allowing:
+ * - push() to navigate forward to a new screen
+ * - pop() to go back to the previous screen
+ * - current() to get the active screen
+ */
+export class ScreenStack {
+    screens = [];
+    /**
+     * Push a new screen onto the stack.
+     * Calls onExit() on current screen and onEnter() on new screen.
+     *
+     * @param screen - Screen to push
+     */
+    push(screen) {
+        // Call exit hook on current screen
+        this.current()?.onExit?.();
+        // Push new screen
+        this.screens.push(screen);
+        // Call enter hook on new screen
+        screen.onEnter?.();
+    }
+    /**
+     * Pop the current screen and return to the previous one.
+     * Calls onExit() on popped screen and onEnter() on revealed screen.
+     *
+     * @returns The popped screen, or null if stack was empty
+     */
+    pop() {
+        if (this.screens.length === 0) {
+            return null;
+        }
+        // Pop and call exit hook
+        const screen = this.screens.pop();
+        if (screen) {
+            screen.onExit?.();
+        }
+        // Call enter hook on now-current screen
+        this.current()?.onEnter?.();
+        return screen ?? null;
+    }
+    /**
+     * Get the current (topmost) screen.
+     *
+     * @returns Current screen, or undefined if stack is empty
+     */
+    current() {
+        return this.screens[this.screens.length - 1];
+    }
+    /**
+     * Get the number of screens in the stack.
+     */
+    size() {
+        return this.screens.length;
+    }
+    /**
+     * Check if the stack is empty.
+     */
+    isEmpty() {
+        return this.screens.length === 0;
+    }
+    /**
+     * Check if there's more than one screen (can go back).
+     */
+    canGoBack() {
+        return this.screens.length > 1;
+    }
+    /**
+     * Clear all screens from the stack.
+     * Calls onExit() on each screen in reverse order.
+     */
+    clear() {
+        while (this.screens.length > 0) {
+            this.pop();
+        }
+    }
+    /**
+     * Replace the current screen with a new one.
+     * Useful for "replace" navigation (no back).
+     *
+     * @param screen - Screen to replace with
+     */
+    replace(screen) {
+        if (this.screens.length > 0) {
+            const current = this.screens.pop();
+            if (current) {
+                current.onExit?.();
+            }
+        }
+        this.screens.push(screen);
+        screen.onEnter?.();
+    }
+}
+// =============================================================================
+// Helper Types
+// =============================================================================
+/**
+ * Helper to create a ScreenResult for staying on the current screen.
+ */
+export function stay(render = true) {
+    return { action: 'stay', render };
+}
+/**
+ * Helper to create a ScreenResult for pushing a new screen.
+ */
+export function pushScreen(screen) {
+    return { action: 'push', screen };
+}
+/**
+ * Helper to create a ScreenResult for popping the current screen.
+ */
+export function popScreen() {
+    return { action: 'pop' };
+}
+/**
+ * Helper to create a ScreenResult for closing the overlay.
+ * Result is optional for void result types.
+ */
+export function closeOverlay(result) {
+    return { action: 'close', result: result };
+}

package/dist/ui/base/tabbed-list-overlay-v2.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Tabbed List Overlay V2
+ *
+ * A reusable base for overlays using the new Overlay interface.
+ * Provides tabs, pagination, search, and detail views.
+ *
+ * Key differences from TabbedListOverlay:
+ * - Extends BaseOverlayV2 (implements new Overlay interface)
+ * - handleKey returns OverlayAction instead of void
+ * - Works with TerminalUI's overlay management
+ * - Keeps ScreenStack internally for detail screen navigation
+ */
+import { BaseOverlayV2 } from './overlay-base-v2.js';
+import { BaseScreen, ScreenStack } from './screen-stack.js';
+import { type PaginationState } from '../features/pagination-feature.js';
+import { type SearchState } from '../features/search-feature.js';
+import type { TabDefinition, TabState } from './overlay-types.js';
+import type { RenderContext, OverlayAction, KeyEvent } from '../overlay/index.js';
+import type { ThemeStyleFunctions } from '../../themes/index.js';
+/**
+ * Configuration for a TabbedListOverlayV2.
+ */
+export interface TabbedListConfigV2<TItem> {
+    /** Title shown in header */
+    title: string;
+    /** Tab definitions */
+    tabs: TabDefinition[];
+    /** All items (will be filtered by tab and search) */
+    items: TItem[];
+    /** Number of items per page (default: 12) */
+    pageSize?: number;
+    /**
+     * Filter items by tab.
+     * Return true to include item in the current tab.
+     */
+    filterByTab: (item: TItem, tabId: string) => boolean;
+    /**
+     * Get searchable text from an item.
+     * Used for search filtering.
+     */
+    getSearchText: (item: TItem) => string;
+    /**
+     * Render an item as a string line.
+     */
+    renderItem: (item: TItem, isSelected: boolean, styles: ThemeStyleFunctions) => string;
+    /** Show count badge in header (default: true) */
+    showCount?: boolean;
+    /** Custom empty state message */
+    emptyMessage?: string;
+    /** Custom no-results message */
+    noResultsMessage?: string;
+    /** Custom footer hints */
+    footerHints?: (searchMode: boolean, activeTabId?: string) => string;
+    /**
+     * Render preview content for the selected item.
+     * Displayed between the list and footer.
+     */
+    renderSelectedPreview?: (item: TItem, styles: ThemeStyleFunctions) => string[];
+    /**
+     * Render sub-header content below the tab bar.
+     * Useful for showing status info like API key status.
+     */
+    renderSubHeader?: (tabId: string, styles: ThemeStyleFunctions) => string[];
+    /**
+     * Handle custom key presses before default handling.
+     * Return { handled: true, render: boolean } to consume the key.
+     * Return { handled: false } to let default handling proceed.
+     */
+    handleCustomKey?: (key: Buffer, tabId: string) => {
+        handled: boolean;
+        render?: boolean;
+        pushScreen?: BaseScreen;
+    };
+}
+/**
+ * State for TabbedListOverlayV2.
+ */
+export interface TabbedListStateV2<TItem> extends TabState, PaginationState, SearchState {
+    /** All items */
+    items: TItem[];
+    /** Filtered items (by tab and search) */
+    filteredItems: TItem[];
+    /** Whether search mode is active */
+    searchMode: boolean;
+}
+/**
+ * Abstract base class for tabbed list overlays using the new Overlay interface.
+ */
+export declare abstract class TabbedListOverlayV2<TItem, TResult = void> extends BaseOverlayV2<TabbedListStateV2<TItem>, TResult> {
+    abstract readonly type: 'fullscreen' | 'inline';
+    abstract readonly id: string;
+    protected readonly screenStack: ScreenStack;
+    protected readonly listConfig: TabbedListConfigV2<TItem>;
+    constructor(config: TabbedListConfigV2<TItem>);
+    /**
+     * Override to create a detail screen for an item.
+     * Return null to disable detail view.
+     */
+    protected createDetailScreen(_item: TItem): BaseScreen | null;
+    /**
+     * Override to handle item selection.
+     * Return a result to close the overlay, or undefined to fall back to detail screen.
+     */
+    protected onItemSelected(_item: TItem): TResult | undefined;
+    protected renderContent(_context: RenderContext): string[];
+    /**
+     * Override render to use the effective minHeight (max of overlay and current screen).
+     */
+    render(context: RenderContext): {
+        lines: string[];
+        minHeight?: number;
+    };
+    handleKey(key: KeyEvent): OverlayAction<TResult>;
+    /**
+     * Get the currently selected item.
+     */
+    protected getSelectedItem(): TItem | undefined;
+}

package/dist/ui/base/tabbed-list-overlay-v2.js

@@ -0,0 +1,335 @@
+/**
+ * Tabbed List Overlay V2
+ *
+ * A reusable base for overlays using the new Overlay interface.
+ * Provides tabs, pagination, search, and detail views.
+ *
+ * Key differences from TabbedListOverlay:
+ * - Extends BaseOverlayV2 (implements new Overlay interface)
+ * - handleKey returns OverlayAction instead of void
+ * - Works with TerminalUI's overlay management
+ * - Keeps ScreenStack internally for detail screen navigation
+ */
+// Terminal width is passed via getWidth callback
+import { BaseOverlayV2 } from './overlay-base-v2.js';
+import { BaseScreen, ScreenStack } from './screen-stack.js';
+import { TabFeature } from '../features/tab-feature.js';
+import { PaginationFeature } from '../features/pagination-feature.js';
+import { SearchFeature } from '../features/search-feature.js';
+import { isCtrlC, isClose, isEscape, isSlash, isEnter } from './key-utils.js';
+import { renderBorder } from './render-utils.js';
+// =============================================================================
+// List Screen V2 (Main View)
+// =============================================================================
+/**
+ * The main list screen for TabbedListOverlayV2.
+ */
+class ListScreenV2 extends BaseScreen {
+    config;
+    state;
+    getStyles;
+    getWidth;
+    createDetailScreen;
+    onItemSelected;
+    tabFeature;
+    pagination;
+    searchFeature;
+    constructor(config, state, getStyles, getWidth, createDetailScreen, onItemSelected) {
+        super();
+        this.config = config;
+        this.state = state;
+        this.getStyles = getStyles;
+        this.getWidth = getWidth;
+        this.createDetailScreen = createDetailScreen;
+        this.onItemSelected = onItemSelected;
+        this.tabFeature = new TabFeature(config.tabs, () => {
+            this.onTabChange();
+        });
+        this.pagination = new PaginationFeature({
+            pageSize: config.pageSize ?? 12,
+        });
+        this.searchFeature = new SearchFeature({
+            onSearch: () => {
+                this.applyFilters();
+            },
+            escapeClearsSearch: false,
+        });
+    }
+    onTabChange() {
+        this.state.selectedIndex = 0;
+        this.state.scrollOffset = 0;
+        this.state.searchMode = false;
+        this.state.searchQuery = '';
+        this.applyFilters();
+    }
+    applyFilters() {
+        const tabId = this.tabFeature.getCurrentTabId(this.state);
+        let filtered = this.state.items.filter((item) => this.config.filterByTab(item, tabId));
+        if (this.state.searchQuery) {
+            filtered = this.searchFeature.filterItems(filtered, this.state, this.config.getSearchText);
+        }
+        this.state.filteredItems = filtered;
+        this.state.selectedIndex = 0;
+        this.state.scrollOffset = 0;
+    }
+    render() {
+        const s = this.getStyles();
+        const cols = this.getWidth();
+        const border = renderBorder(cols, s);
+        const pageSize = this.config.pageSize ?? 12;
+        const lines = [];
+        // Header
+        lines.push(border);
+        const showCount = this.config.showCount ?? true;
+        const countBadge = showCount
+            ? s.muted(` [${String(this.state.filteredItems.length)}/${String(this.state.items.length)}]`)
+            : '';
+        lines.push(`  ${s.primaryBold(this.config.title)}${countBadge}`);
+        lines.push('');
+        // Tab bar with hint
+        const tabBar = this.tabFeature.renderTabs(this.state, s);
+        const tabHint = s.muted(`(${this.tabFeature.renderHints()})`);
+        lines.push(`  ${tabBar}  ${tabHint}`);
+        lines.push('');
+        // Sub-header (if provided) - e.g., API key status
+        if (this.config.renderSubHeader) {
+            const tabId = this.tabFeature.getCurrentTabId(this.state);
+            const subHeaderLines = this.config.renderSubHeader(tabId, s);
+            lines.push(...subHeaderLines);
+        }
+        // Search box (if in search mode)
+        if (this.state.searchMode) {
+            const query = this.state.searchQuery;
+            lines.push(`  ${s.muted('Search:')} ${query ? s.primary(query) : ''}█`);
+            lines.push('');
+        }
+        // Items
+        const visibleItems = this.pagination.getVisibleItems(this.state, this.state.filteredItems);
+        if (visibleItems.length === 0) {
+            const msg = this.state.searchQuery
+                ? (this.config.noResultsMessage ?? 'No items match the search.')
+                : (this.config.emptyMessage ?? 'No items available.');
+            lines.push(`    ${s.muted(msg)}`);
+            for (let i = 0; i < pageSize - 1; i++) {
+                lines.push('');
+            }
+        }
+        else {
+            for (let i = 0; i < visibleItems.length; i++) {
+                const item = visibleItems[i];
+                const absoluteIndex = this.state.scrollOffset + i;
+                const isSelected = absoluteIndex === this.state.selectedIndex;
+                lines.push(this.config.renderItem(item, isSelected, s));
+            }
+            // Pad to fixed height
+            for (let i = visibleItems.length; i < pageSize; i++) {
+                lines.push('');
+            }
+        }
+        // Pagination indicator
+        lines.push('');
+        const indicator = this.pagination.renderIndicator(this.state, this.state.filteredItems.length, s);
+        if (indicator) {
+            lines.push(indicator);
+        }
+        // Selected item preview
+        if (this.config.renderSelectedPreview && visibleItems.length > 0) {
+            const selectedItem = this.state.filteredItems[this.state.selectedIndex];
+            if (selectedItem) {
+                lines.push('');
+                const previewLines = this.config.renderSelectedPreview(selectedItem, s);
+                lines.push(...previewLines);
+            }
+        }
+        // Footer
+        lines.push(border);
+        lines.push(`  ${s.muted(this.getFooterHints())}`);
+        lines.push(border);
+        return lines;
+    }
+    getFooterHints() {
+        if (this.config.footerHints) {
+            const activeTab = this.config.tabs[this.state.currentTab];
+            return this.config.footerHints(this.state.searchMode, activeTab.id);
+        }
+        if (this.state.searchMode) {
+            return 'Type to filter · ↑↓/jk Navigate · Enter Details · Esc Exit search';
+        }
+        return this.pagination.renderHints() + ' · / Search · Enter Details · q/Esc Close';
+    }
+    handleKey(data) {
+        // Ctrl+C always closes
+        if (isCtrlC(data)) {
+            return { action: 'close', result: undefined };
+        }
+        // Search mode handling
+        if (this.state.searchMode) {
+            if (isEscape(data)) {
+                this.state.searchMode = false;
+                if (this.state.searchQuery) {
+                    this.state.searchQuery = '';
+                    this.applyFilters();
+                }
+                return { action: 'stay', render: true };
+            }
+            const searchResult = this.searchFeature.handleKey(data, this.state);
+            if (searchResult?.handled) {
+                return { action: 'stay', render: searchResult.action === 'render' };
+            }
+            if (isEnter(data)) {
+                return this.handleEnter();
+            }
+            const paginationResult = this.pagination.handleKey(data, this.state, this.state.filteredItems.length);
+            if (paginationResult?.handled) {
+                return { action: 'stay', render: paginationResult.action === 'render' };
+            }
+            return { action: 'stay', render: false };
+        }
+        // Not in search mode
+        // Custom key handling (before default handling)
+        if (this.config.handleCustomKey) {
+            const tabId = this.tabFeature.getCurrentTabId(this.state);
+            const customResult = this.config.handleCustomKey(data, tabId);
+            if (customResult.handled) {
+                if (customResult.pushScreen) {
+                    return { action: 'push', screen: customResult.pushScreen };
+                }
+                return { action: 'stay', render: customResult.render ?? false };
+            }
+        }
+        if (isSlash(data)) {
+            this.state.searchMode = true;
+            return { action: 'stay', render: true };
+        }
+        if (isClose(data)) {
+            return { action: 'close', result: undefined };
+        }
+        // Tab navigation
+        const tabResult = this.tabFeature.handleKey(data, this.state);
+        if (tabResult?.handled) {
+            return { action: 'stay', render: tabResult.action === 'render' };
+        }
+        // Enter shows detail
+        if (isEnter(data)) {
+            return this.handleEnter();
+        }
+        // Pagination
+        const paginationResult = this.pagination.handleKey(data, this.state, this.state.filteredItems.length);
+        if (paginationResult?.handled) {
+            return { action: 'stay', render: paginationResult.action === 'render' };
+        }
+        return { action: 'stay', render: false };
+    }
+    handleEnter() {
+        if (this.state.filteredItems.length === 0) {
+            return { action: 'stay', render: false };
+        }
+        const item = this.state.filteredItems[this.state.selectedIndex];
+        // First, check if there's an item selection handler
+        if (this.onItemSelected) {
+            const result = this.onItemSelected(item);
+            if (result !== undefined) {
+                // Item was selected, close overlay with result
+                return { action: 'close', result };
+            }
+        }
+        // Fall back to detail screen
+        const detailScreen = this.createDetailScreen(item);
+        if (detailScreen) {
+            return { action: 'push', screen: detailScreen };
+        }
+        return { action: 'stay', render: false };
+    }
+}
+// =============================================================================
+// TabbedListOverlayV2 Base Class
+// =============================================================================
+/**
+ * Abstract base class for tabbed list overlays using the new Overlay interface.
+ */
+export class TabbedListOverlayV2 extends BaseOverlayV2 {
+    screenStack;
+    listConfig;
+    constructor(config) {
+        const initialState = {
+            currentTab: 0,
+            selectedIndex: 0,
+            scrollOffset: 0,
+            searchQuery: '',
+            searchMode: false,
+            items: config.items,
+            filteredItems: config.items.filter((item) => config.filterByTab(item, config.tabs[0]?.id ?? 'all')),
+        };
+        super(initialState);
+        this.listConfig = config;
+        // Calculate minimum height for stable rendering:
+        // Header (5) + pageSize items + pagination (2) + footer (3) = 10 + pageSize
+        const pageSize = config.pageSize ?? 12;
+        this.minHeight = 10 + pageSize;
+        this.screenStack = new ScreenStack();
+        this.screenStack.push(new ListScreenV2(config, this.state, () => this.getStyles(), () => this.termWidth, (item) => this.createDetailScreen(item), (item) => this.onItemSelected(item)));
+    }
+    /**
+     * Override to create a detail screen for an item.
+     * Return null to disable detail view.
+     */
+    createDetailScreen(_item) {
+        return null;
+    }
+    /**
+     * Override to handle item selection.
+     * Return a result to close the overlay, or undefined to fall back to detail screen.
+     */
+    onItemSelected(_item) {
+        return undefined;
+    }
+    renderContent(_context) {
+        const screen = this.screenStack.current();
+        return screen?.render() ?? [];
+    }
+    /**
+     * Override render to use the effective minHeight (max of overlay and current screen).
+     */
+    render(context) {
+        // Cache context values for helper methods
+        this.styles = context.styles;
+        this.termWidth = context.width;
+        // Get content from subclass
+        const lines = this.renderContent(context);
+        // Calculate effective minHeight: max of overlay's base and current screen's minHeight
+        const screen = this.screenStack.current();
+        const screenMinHeight = screen?.getMinHeight?.() ?? 0;
+        const effectiveMinHeight = Math.max(this.minHeight, screenMinHeight);
+        return effectiveMinHeight > 0 ? { lines, minHeight: effectiveMinHeight } : { lines };
+    }
+    handleKey(key) {
+        // Convert KeyEvent to Buffer for old-style BaseScreen.handleKey
+        const data = key.raw;
+        const screen = this.screenStack.current();
+        if (!screen) {
+            return this.cancel();
+        }
+        const result = screen.handleKey(data);
+        switch (result.action) {
+            case 'stay':
+                return result.render ? this.rerender() : this.noAction();
+            case 'push':
+                this.screenStack.push(result.screen);
+                return this.rerender();
+            case 'pop':
+                this.screenStack.pop();
+                return this.rerender();
+            case 'close':
+                if (result.result !== undefined) {
+                    return this.close(result.result);
+                }
+                return this.cancel();
+        }
+    }
+    /**
+     * Get the currently selected item.
+     */
+    getSelectedItem() {
+        return this.state.filteredItems[this.state.selectedIndex];
+    }
+}