@compilr-dev/cli 0.4.0 → 0.5.0

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

@@ -0,0 +1,154 @@
+/**
+ * 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)
+ *     ];
+ *   }
+ * }
+ * ```
+ */
+/**
+ * State interface for pagination.
+ * Overlay state should extend this.
+ */
+export interface PaginationState {
+    /** Currently selected index (0-based) */
+    selectedIndex: number;
+    /** First visible item index */
+    scrollOffset: number;
+}
+/**
+ * Configuration for PaginationFeature.
+ */
+export interface PaginationConfig {
+    /** Number of items visible per page */
+    pageSize: number;
+    /**
+     * Whether left/right arrows trigger page navigation.
+     * Default: true
+     */
+    useArrowsForPaging?: boolean;
+}
+/**
+ * Result from handling a key.
+ */
+export interface PaginationKeyResult {
+    /** Whether the key was handled */
+    handled: boolean;
+    /** Action to take */
+    action?: 'render' | 'none';
+}
+/**
+ * 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 declare class PaginationFeature {
+    private readonly pageSize;
+    private readonly useArrowsForPaging;
+    constructor(config: PaginationConfig);
+    /**
+     * 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: Buffer, state: PaginationState, totalItems: number): PaginationKeyResult | null;
+    /**
+     * Ensure the selected item is visible by adjusting scrollOffset.
+     *
+     * @param state - State to adjust
+     * @param totalItems - Total number of items
+     */
+    ensureVisible(state: PaginationState, totalItems: number): void;
+    /**
+     * Get the visible slice of items.
+     *
+     * @param state - State containing scrollOffset
+     * @param items - All items
+     * @returns Visible items
+     */
+    getVisibleItems<T>(state: PaginationState, items: T[]): T[];
+    /**
+     * 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: PaginationState, totalItems: number): {
+        start: number;
+        end: number;
+        total: number;
+        canScrollUp: boolean;
+        canScrollDown: boolean;
+    };
+    /**
+     * 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: PaginationState, totalItems: number, styles: {
+        muted: (s: string) => string;
+    }): string;
+    /**
+     * Render navigation hints for the footer.
+     *
+     * @param includeArrows - Whether to include ←→/hl hints
+     * @returns Hint string
+     */
+    renderHints(includeArrows?: boolean): string;
+    /**
+     * Get the page size.
+     */
+    getPageSize(): number;
+    /**
+     * Reset pagination state to beginning.
+     *
+     * @param state - State to reset
+     */
+    reset(state: PaginationState): void;
+    /**
+     * 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: PaginationState, index: number, totalItems: number): void;
+}

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[];
+}