@compilr-dev/cli 0.4.0 → 0.5.1

package/dist/ui/features/pagination-feature.js

@@ -0,0 +1,238 @@
+/**
+ * Pagination Feature
+ *
+ * Composable feature for paginated list navigation.
+ * Handles page up/down, scroll offset tracking, and visibility.
+ *
+ * Usage:
+ * ```typescript
+ * interface MyState extends OverlayState, PaginationState {
+ *   items: string[];
+ * }
+ *
+ * class MyScreen extends BaseScreen {
+ *   private pagination = new PaginationFeature({ pageSize: 12 });
+ *
+ *   handleKey(data: Buffer): ScreenResult {
+ *     const result = this.pagination.handleKey(data, this.state, this.state.items.length);
+ *     if (result?.handled) {
+ *       return result.action === 'render' ? stay() : stay(false);
+ *     }
+ *     // ... other key handling
+ *   }
+ *
+ *   render(): string[] {
+ *     const visible = this.pagination.getVisibleItems(this.state, this.state.items);
+ *     // render visible items...
+ *     return [
+ *       ...itemLines,
+ *       this.pagination.renderIndicator(this.state, this.state.items.length, styles)
+ *     ];
+ *   }
+ * }
+ * ```
+ */
+import { isNavigateUp, isNavigateDown, isNavigateLeft, isNavigateRight, isPageUp, isPageDown, } from '../base/key-utils.js';
+// =============================================================================
+// PaginationFeature Class
+// =============================================================================
+/**
+ * Feature for paginated list navigation.
+ *
+ * Handles:
+ * - Up/Down arrows and j/k for item navigation
+ * - Left/Right arrows and h/l for page navigation
+ * - Page Up/Page Down for page navigation
+ * - Scroll offset tracking
+ * - Visibility management (ensure selected item is visible)
+ */
+export class PaginationFeature {
+    pageSize;
+    useArrowsForPaging;
+    constructor(config) {
+        this.pageSize = config.pageSize;
+        this.useArrowsForPaging = config.useArrowsForPaging ?? true;
+    }
+    // ===========================================================================
+    // Key Handling
+    // ===========================================================================
+    /**
+     * Handle a key press.
+     *
+     * @param data - Raw key buffer
+     * @param state - State containing selectedIndex and scrollOffset
+     * @param totalItems - Total number of items in the list
+     * @returns Result if handled, null otherwise
+     */
+    handleKey(data, state, totalItems) {
+        if (totalItems === 0) {
+            return null;
+        }
+        // Navigate up (single item)
+        if (isNavigateUp(data)) {
+            if (state.selectedIndex > 0) {
+                state.selectedIndex--;
+                this.ensureVisible(state, totalItems);
+                return { handled: true, action: 'render' };
+            }
+            return { handled: true, action: 'none' };
+        }
+        // Navigate down (single item)
+        if (isNavigateDown(data)) {
+            if (state.selectedIndex < totalItems - 1) {
+                state.selectedIndex++;
+                this.ensureVisible(state, totalItems);
+                return { handled: true, action: 'render' };
+            }
+            return { handled: true, action: 'none' };
+        }
+        // Page up (PgUp or ←/h if enabled)
+        const isPageUpKey = isPageUp(data) || (this.useArrowsForPaging && isNavigateLeft(data));
+        if (isPageUpKey) {
+            const newIndex = Math.max(0, state.selectedIndex - this.pageSize);
+            if (newIndex !== state.selectedIndex) {
+                state.selectedIndex = newIndex;
+                this.ensureVisible(state, totalItems);
+                return { handled: true, action: 'render' };
+            }
+            return { handled: true, action: 'none' };
+        }
+        // Page down (PgDn or →/l if enabled)
+        const isPageDownKey = isPageDown(data) || (this.useArrowsForPaging && isNavigateRight(data));
+        if (isPageDownKey) {
+            const newIndex = Math.min(totalItems - 1, state.selectedIndex + this.pageSize);
+            if (newIndex !== state.selectedIndex) {
+                state.selectedIndex = newIndex;
+                this.ensureVisible(state, totalItems);
+                return { handled: true, action: 'render' };
+            }
+            return { handled: true, action: 'none' };
+        }
+        return null;
+    }
+    // ===========================================================================
+    // Visibility Management
+    // ===========================================================================
+    /**
+     * Ensure the selected item is visible by adjusting scrollOffset.
+     *
+     * @param state - State to adjust
+     * @param totalItems - Total number of items
+     */
+    ensureVisible(state, totalItems) {
+        // Clamp selectedIndex first
+        if (state.selectedIndex < 0) {
+            state.selectedIndex = 0;
+        }
+        else if (state.selectedIndex >= totalItems) {
+            state.selectedIndex = Math.max(0, totalItems - 1);
+        }
+        // Adjust scrollOffset to keep selection visible
+        if (state.selectedIndex < state.scrollOffset) {
+            state.scrollOffset = state.selectedIndex;
+        }
+        else if (state.selectedIndex >= state.scrollOffset + this.pageSize) {
+            state.scrollOffset = state.selectedIndex - this.pageSize + 1;
+        }
+        // Clamp scrollOffset
+        const maxOffset = Math.max(0, totalItems - this.pageSize);
+        if (state.scrollOffset > maxOffset) {
+            state.scrollOffset = maxOffset;
+        }
+        if (state.scrollOffset < 0) {
+            state.scrollOffset = 0;
+        }
+    }
+    // ===========================================================================
+    // Item Access
+    // ===========================================================================
+    /**
+     * Get the visible slice of items.
+     *
+     * @param state - State containing scrollOffset
+     * @param items - All items
+     * @returns Visible items
+     */
+    getVisibleItems(state, items) {
+        return items.slice(state.scrollOffset, state.scrollOffset + this.pageSize);
+    }
+    /**
+     * Get the visible range info.
+     *
+     * @param state - State containing scrollOffset
+     * @param totalItems - Total number of items
+     * @returns Object with start, end, total, canScrollUp, canScrollDown
+     */
+    getVisibleRange(state, totalItems) {
+        const start = state.scrollOffset + 1; // 1-based for display
+        const end = Math.min(state.scrollOffset + this.pageSize, totalItems);
+        return {
+            start,
+            end,
+            total: totalItems,
+            canScrollUp: state.scrollOffset > 0,
+            canScrollDown: state.scrollOffset + this.pageSize < totalItems,
+        };
+    }
+    // ===========================================================================
+    // Rendering Helpers
+    // ===========================================================================
+    /**
+     * Render a scroll indicator line.
+     *
+     * @param state - State containing scrollOffset
+     * @param totalItems - Total number of items
+     * @param styles - Theme styles with muted() function
+     * @returns Formatted indicator string (empty if no pagination needed)
+     */
+    renderIndicator(state, totalItems, styles) {
+        if (totalItems <= this.pageSize) {
+            return ''; // No pagination needed
+        }
+        const range = this.getVisibleRange(state, totalItems);
+        const info = `${String(range.start)}-${String(range.end)} of ${String(range.total)}`;
+        const arrows = (range.canScrollUp ? '↑' : ' ') + (range.canScrollDown ? '↓' : ' ');
+        return `  ${styles.muted(info)}  ${styles.muted(arrows)}`;
+    }
+    /**
+     * Render navigation hints for the footer.
+     *
+     * @param includeArrows - Whether to include ←→/hl hints
+     * @returns Hint string
+     */
+    renderHints(includeArrows = true) {
+        if (includeArrows) {
+            return '↑↓/jk Navigate · ←→/hl Page';
+        }
+        return '↑↓/jk Navigate · PgUp/PgDn Page';
+    }
+    // ===========================================================================
+    // Utilities
+    // ===========================================================================
+    /**
+     * Get the page size.
+     */
+    getPageSize() {
+        return this.pageSize;
+    }
+    /**
+     * Reset pagination state to beginning.
+     *
+     * @param state - State to reset
+     */
+    reset(state) {
+        state.selectedIndex = 0;
+        state.scrollOffset = 0;
+    }
+    /**
+     * Jump to a specific index and ensure it's visible.
+     *
+     * @param state - State to update
+     * @param index - Target index
+     * @param totalItems - Total number of items
+     */
+    jumpTo(state, index, totalItems) {
+        state.selectedIndex = Math.max(0, Math.min(index, totalItems - 1));
+        this.ensureVisible(state, totalItems);
+    }
+}

package/dist/ui/features/search-feature.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Search Feature
+ *
+ * Composable feature for search/filter text input in overlays.
+ * Handles typing, backspace, and escape to clear.
+ *
+ * Usage:
+ * ```typescript
+ * interface MyState extends OverlayState, SearchState {
+ *   items: string[];
+ * }
+ *
+ * class MyScreen extends BaseScreen {
+ *   private search = new SearchFeature({
+ *     onSearch: (query) => this.filterItems(query),
+ *   });
+ *
+ *   handleKey(data: Buffer): ScreenResult {
+ *     const result = this.search.handleKey(data, this.state);
+ *     if (result?.handled) {
+ *       return result.action === 'render' ? stay() : stay(false);
+ *     }
+ *     // ... other key handling
+ *   }
+ *
+ *   render(): string[] {
+ *     return [
+ *       this.search.renderSearchBox(this.state, styles, { label: 'Search' }),
+ *       ...filteredItemLines,
+ *     ];
+ *   }
+ * }
+ * ```
+ */
+/**
+ * State interface for search.
+ * Overlay state should extend this.
+ */
+export interface SearchState {
+    /** Current search query */
+    searchQuery: string;
+}
+/**
+ * Configuration for SearchFeature.
+ */
+export interface SearchConfig {
+    /**
+     * Callback when search query changes.
+     * Use this to trigger filtering/re-rendering.
+     */
+    onSearch?: (query: string) => void;
+    /**
+     * Whether Escape clears the search (default: true).
+     * If false, Escape is not handled by this feature.
+     */
+    escapeClearsSearch?: boolean;
+    /**
+     * Placeholder text when search is empty.
+     */
+    placeholder?: string;
+}
+/**
+ * Result from handling a key.
+ */
+export interface SearchKeyResult {
+    /** Whether the key was handled */
+    handled: boolean;
+    /** Action to take */
+    action?: 'render' | 'none';
+    /** Whether the search was cleared (Escape pressed) */
+    cleared?: boolean;
+}
+/**
+ * Options for rendering the search box.
+ */
+export interface SearchBoxOptions {
+    /** Label before the search box (default: 'Search') */
+    label?: string;
+    /** Whether to show cursor (default: true) */
+    showCursor?: boolean;
+    /** Prefix before the input (default: ' ') */
+    prefix?: string;
+}
+/**
+ * Feature for search/filter text input.
+ *
+ * Handles:
+ * - Printable character input
+ * - Backspace to delete
+ * - Escape to clear (optional)
+ */
+export declare class SearchFeature {
+    private readonly config;
+    constructor(config?: SearchConfig);
+    /**
+     * Handle a key press.
+     *
+     * @param data - Raw key buffer
+     * @param state - State containing searchQuery
+     * @returns Result if handled, null otherwise
+     */
+    handleKey(data: Buffer, state: SearchState): SearchKeyResult | null;
+    /**
+     * Render a search box with optional cursor.
+     *
+     * @param state - State containing searchQuery
+     * @param styles - Theme styles
+     * @param options - Rendering options
+     * @returns Formatted search box string
+     */
+    renderSearchBox(state: SearchState, styles: {
+        muted: (s: string) => string;
+        primary?: (s: string) => string;
+    }, options?: SearchBoxOptions): string;
+    /**
+     * Render search hints for the footer.
+     *
+     * @param hasQuery - Whether there's an active search query
+     * @returns Hint string
+     */
+    renderHints(hasQuery?: boolean): string;
+    /**
+     * Check if there's an active search query.
+     */
+    hasQuery(state: SearchState): boolean;
+    /**
+     * Get the current search query.
+     */
+    getQuery(state: SearchState): string;
+    /**
+     * Clear the search query.
+     */
+    clear(state: SearchState): void;
+    /**
+     * Set the search query programmatically.
+     */
+    setQuery(state: SearchState, query: string): void;
+    /**
+     * Filter items based on search query.
+     * Generic helper that works with any item type.
+     *
+     * @param items - Items to filter
+     * @param state - State containing searchQuery
+     * @param getSearchableText - Function to extract searchable text from item
+     * @returns Filtered items
+     */
+    filterItems<T>(items: T[], state: SearchState, getSearchableText: (item: T) => string): T[];
+}

package/dist/ui/features/search-feature.js

@@ -0,0 +1,185 @@
+/**
+ * Search Feature
+ *
+ * Composable feature for search/filter text input in overlays.
+ * Handles typing, backspace, and escape to clear.
+ *
+ * Usage:
+ * ```typescript
+ * interface MyState extends OverlayState, SearchState {
+ *   items: string[];
+ * }
+ *
+ * class MyScreen extends BaseScreen {
+ *   private search = new SearchFeature({
+ *     onSearch: (query) => this.filterItems(query),
+ *   });
+ *
+ *   handleKey(data: Buffer): ScreenResult {
+ *     const result = this.search.handleKey(data, this.state);
+ *     if (result?.handled) {
+ *       return result.action === 'render' ? stay() : stay(false);
+ *     }
+ *     // ... other key handling
+ *   }
+ *
+ *   render(): string[] {
+ *     return [
+ *       this.search.renderSearchBox(this.state, styles, { label: 'Search' }),
+ *       ...filteredItemLines,
+ *     ];
+ *   }
+ * }
+ * ```
+ */
+import { isBackspace, isEscape, isPrintable, getPrintableChar, } from '../base/key-utils.js';
+// =============================================================================
+// SearchFeature Class
+// =============================================================================
+/**
+ * Feature for search/filter text input.
+ *
+ * Handles:
+ * - Printable character input
+ * - Backspace to delete
+ * - Escape to clear (optional)
+ */
+export class SearchFeature {
+    config;
+    constructor(config = {}) {
+        this.config = {
+            escapeClearsSearch: true,
+            placeholder: '',
+            ...config,
+        };
+    }
+    // ===========================================================================
+    // Key Handling
+    // ===========================================================================
+    /**
+     * Handle a key press.
+     *
+     * @param data - Raw key buffer
+     * @param state - State containing searchQuery
+     * @returns Result if handled, null otherwise
+     */
+    handleKey(data, state) {
+        // Escape clears search
+        if (this.config.escapeClearsSearch && isEscape(data)) {
+            if (state.searchQuery.length > 0) {
+                state.searchQuery = '';
+                this.config.onSearch?.(state.searchQuery);
+                return { handled: true, action: 'render', cleared: true };
+            }
+            // Don't handle Escape if search is already empty
+            return null;
+        }
+        // Backspace deletes last character
+        if (isBackspace(data)) {
+            if (state.searchQuery.length > 0) {
+                state.searchQuery = state.searchQuery.slice(0, -1);
+                this.config.onSearch?.(state.searchQuery);
+                return { handled: true, action: 'render' };
+            }
+            return { handled: true, action: 'none' };
+        }
+        // Printable characters add to search
+        if (isPrintable(data)) {
+            const char = getPrintableChar(data);
+            if (char) {
+                state.searchQuery += char;
+                this.config.onSearch?.(state.searchQuery);
+                return { handled: true, action: 'render' };
+            }
+        }
+        return null;
+    }
+    // ===========================================================================
+    // Rendering
+    // ===========================================================================
+    /**
+     * Render a search box with optional cursor.
+     *
+     * @param state - State containing searchQuery
+     * @param styles - Theme styles
+     * @param options - Rendering options
+     * @returns Formatted search box string
+     */
+    renderSearchBox(state, styles, options = {}) {
+        const label = options.label ?? 'Search';
+        const showCursor = options.showCursor ?? true;
+        const prefix = options.prefix ?? ' ';
+        const cursor = showCursor ? '█' : '';
+        const query = state.searchQuery;
+        const placeholder = !query && this.config.placeholder
+            ? styles.muted(this.config.placeholder)
+            : '';
+        if (query) {
+            const styledQuery = styles.primary
+                ? styles.primary(query)
+                : query;
+            return `${prefix}${label}: ${styledQuery}${cursor}`;
+        }
+        return `${prefix}${label}: ${placeholder}${cursor}`;
+    }
+    /**
+     * Render search hints for the footer.
+     *
+     * @param hasQuery - Whether there's an active search query
+     * @returns Hint string
+     */
+    renderHints(hasQuery = false) {
+        if (hasQuery && this.config.escapeClearsSearch) {
+            return 'Type to search · Esc Clear';
+        }
+        return 'Type to search';
+    }
+    // ===========================================================================
+    // Utilities
+    // ===========================================================================
+    /**
+     * Check if there's an active search query.
+     */
+    hasQuery(state) {
+        return state.searchQuery.length > 0;
+    }
+    /**
+     * Get the current search query.
+     */
+    getQuery(state) {
+        return state.searchQuery;
+    }
+    /**
+     * Clear the search query.
+     */
+    clear(state) {
+        state.searchQuery = '';
+        this.config.onSearch?.(state.searchQuery);
+    }
+    /**
+     * Set the search query programmatically.
+     */
+    setQuery(state, query) {
+        state.searchQuery = query;
+        this.config.onSearch?.(state.searchQuery);
+    }
+    /**
+     * Filter items based on search query.
+     * Generic helper that works with any item type.
+     *
+     * @param items - Items to filter
+     * @param state - State containing searchQuery
+     * @param getSearchableText - Function to extract searchable text from item
+     * @returns Filtered items
+     */
+    filterItems(items, state, getSearchableText) {
+        const query = state.searchQuery.toLowerCase().trim();
+        if (!query) {
+            return items;
+        }
+        return items.filter((item) => {
+            const text = getSearchableText(item).toLowerCase();
+            return text.includes(query);
+        });
+    }
+}