@compilr-dev/cli 0.4.0 → 0.5.0

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

@@ -0,0 +1,103 @@
+/**
+ * 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) => string;
+    /**
+     * Render preview content for the selected item.
+     * Displayed between the list and footer.
+     */
+    renderSelectedPreview?: (item: TItem, styles: ThemeStyleFunctions) => string[];
+}
+/**
+ * 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,317 @@
+/**
+ * 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('');
+        // 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) {
+            return this.config.footerHints(this.state.searchMode);
+        }
+        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
+        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];
+    }
+}

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

@@ -0,0 +1,153 @@
+/**
+ * Tabbed List Overlay Base Class
+ *
+ * A reusable base for overlays that display:
+ * - Tabs for filtering/categorizing
+ * - A paginated list of items
+ * - Search mode (activated with /)
+ * - Detail view (via ScreenStack)
+ *
+ * This provides ~80% of the common overlay functionality,
+ * leaving only item-specific rendering to be customized.
+ *
+ * Usage:
+ * ```typescript
+ * interface MyItem { name: string; description: string; }
+ *
+ * const TABS = [
+ *   { id: 'all', label: 'All' },
+ *   { id: 'active', label: 'Active' },
+ * ];
+ *
+ * class MyOverlay extends TabbedListOverlay<MyItem, MyResult> {
+ *   constructor(items: MyItem[]) {
+ *     super({
+ *       title: 'My Items',
+ *       tabs: TABS,
+ *       items,
+ *       pageSize: 12,
+ *       filterByTab: (item, tabId) => tabId === 'all' || item.active,
+ *       getSearchText: (item) => `${item.name} ${item.description}`,
+ *       renderItem: (item, isSelected, styles) => {
+ *         const prefix = isSelected ? '❯ ' : '  ';
+ *         return prefix + item.name;
+ *       },
+ *     });
+ *   }
+ *
+ *   // Optional: Override to add detail view
+ *   protected createDetailScreen(item: MyItem): BaseScreen | null {
+ *     return new MyDetailScreen(item, this.styles);
+ *   }
+ * }
+ * ```
+ */
+import { BaseOverlay, type OverlayState } from './overlay-base.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';
+/**
+ * Configuration for a TabbedListOverlay.
+ */
+export interface TabbedListConfig<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.
+     * @param item - The item to render
+     * @param isSelected - Whether this item is currently selected
+     * @param styles - Theme styles
+     * @returns Single line string
+     */
+    renderItem: (item: TItem, isSelected: boolean, styles: ReturnType<typeof import('../../themes/index.js').getStyles>) => string;
+    /**
+     * Optional: Show count badge in header (default: true)
+     */
+    showCount?: boolean;
+    /**
+     * Optional: Custom empty state message
+     */
+    emptyMessage?: string;
+    /**
+     * Optional: Custom no-results message
+     */
+    noResultsMessage?: string;
+    /**
+     * Optional: Custom footer hints
+     * @param searchMode - Whether search mode is active
+     * @returns Footer hints string
+     */
+    footerHints?: (searchMode: boolean) => string;
+    /**
+     * Optional: Render preview content for the selected item
+     * Displayed between the list and footer
+     * @param item - The currently selected item
+     * @param styles - Theme styles
+     * @returns Array of lines to render
+     */
+    renderSelectedPreview?: (item: TItem, styles: ReturnType<typeof import('../../themes/index.js').getStyles>) => string[];
+    /**
+     * Optional: Whether detail screens take over full screen.
+     * When true (default), returning from a detail screen clears the screen.
+     * When false, screens render in-place without clearing.
+     */
+    detailScreensFullScreen?: boolean;
+}
+/**
+ * State for TabbedListOverlay.
+ */
+export interface TabbedListState<TItem> extends OverlayState, 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.
+ *
+ * Provides:
+ * - Tab-based filtering
+ * - Search mode with / toggle
+ * - Paginated item display
+ * - ScreenStack for detail views
+ *
+ * Subclasses can override createDetailScreen() to add detail views.
+ */
+export declare abstract class TabbedListOverlay<TItem, TResult = void> extends BaseOverlay<TabbedListState<TItem>, TResult> {
+    protected readonly screenStack: ScreenStack;
+    protected readonly listConfig: TabbedListConfig<TItem>;
+    private resizeHandler;
+    constructor(config: TabbedListConfig<TItem>);
+    /**
+     * Override to create a detail screen for an item.
+     * Return null to disable detail view.
+     */
+    protected createDetailScreen(_item: TItem): BaseScreen | null;
+    show(): Promise<TResult>;
+    protected close(result: TResult): void;
+    render(): string[];
+    handleKey(data: Buffer): void;
+    /**
+     * Get the currently selected item.
+     */
+    protected getSelectedItem(): TItem | undefined;
+}