@compilr-dev/cli 0.4.0 → 0.5.0

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);
+        });
+    }
+}

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

@@ -0,0 +1,194 @@
+/**
+ * Tab Feature
+ *
+ * Composable feature for tab/filter navigation.
+ * Handles Tab/Shift+Tab and number keys for tab switching.
+ *
+ * Note: Arrow keys (←→/hl) are NOT used for tabs - they are reserved
+ * for page navigation in paginated overlays. This ensures consistent
+ * keyboard behavior across all overlays.
+ *
+ * Usage:
+ * ```typescript
+ * const TABS = [
+ *   { id: 'all', label: 'All' },
+ *   { id: 'active', label: 'Active' },
+ *   { id: 'completed', label: 'Completed' },
+ * ];
+ *
+ * interface MyState extends OverlayState, TabState {
+ *   // ...
+ * }
+ *
+ * class MyOverlay extends BaseOverlay<MyState, void> {
+ *   private tabFeature = new TabFeature(TABS, (tabId) => {
+ *     this.onTabChange(tabId);
+ *   });
+ *
+ *   handleKey(data: Buffer): void {
+ *     const result = this.tabFeature.handleKey(data, this.state);
+ *     if (result?.handled) {
+ *       if (result.action === 'render') this.update();
+ *       return;
+ *     }
+ *     // ... other key handling
+ *   }
+ *
+ *   render(): string[] {
+ *     return [
+ *       ...this.renderHeader('My Overlay'),
+ *       ' ' + this.tabFeature.renderTabs(this.state, this.styles),
+ *       '',
+ *       // ... content
+ *       ...this.renderFooter(this.tabFeature.renderHints() + ' · ↑↓/jk Navigate')
+ *     ];
+ *   }
+ * }
+ * ```
+ */
+import type { KeyResult, TabState, TabDefinition } from '../base/overlay-types.js';
+/**
+ * Configuration for TabFeature.
+ */
+export interface TabFeatureConfig {
+    /**
+     * Tab definitions.
+     */
+    tabs: TabDefinition[];
+    /**
+     * Callback when tab changes.
+     * @param tabId - ID of the new tab
+     * @param index - Index of the new tab
+     */
+    onChange?: (tabId: string, index: number) => void;
+    /**
+     * Whether to use number keys (1-9) for direct tab selection.
+     * Default: true (if tabs.length <= 9)
+     */
+    useNumberKeys?: boolean;
+    /**
+     * Whether navigation wraps at boundaries.
+     * Default: true
+     */
+    wrapNavigation?: boolean;
+}
+/**
+ * Feature for tab/filter navigation.
+ *
+ * Handles:
+ * - Tab/Shift+Tab for cycling tabs
+ * - Number keys 1-9 for direct selection (optional)
+ *
+ * Note: Arrow keys are NOT handled - they are reserved for pagination.
+ */
+export declare class TabFeature {
+    private readonly config;
+    /**
+     * Create a new TabFeature.
+     *
+     * @param tabs - Tab definitions
+     * @param onChange - Optional callback when tab changes
+     */
+    constructor(tabs: TabDefinition[], onChange?: (tabId: string, index: number) => void);
+    /**
+     * Create from config object (alternative constructor).
+     */
+    static fromConfig(config: TabFeatureConfig): TabFeature;
+    /**
+     * Handle a key press.
+     *
+     * @param data - Raw key buffer
+     * @param state - State containing currentTab
+     * @returns KeyResult if handled, null otherwise
+     */
+    handleKey(data: Buffer, state: TabState): KeyResult | null;
+    /**
+     * Render tabs in a row.
+     *
+     * @param state - State containing currentTab
+     * @param styles - Theme styles
+     * @returns Rendered tab bar string
+     */
+    renderTabs(state: TabState, styles: {
+        selected: (s: string) => string;
+        muted: (s: string) => string;
+    }): string;
+    /**
+     * Render tabs with number key hints.
+     *
+     * @param state - State containing currentTab
+     * @param styles - Theme styles
+     * @returns Rendered tab bar string with numbers
+     */
+    renderTabsWithNumbers(state: TabState, styles: {
+        selected: (s: string) => string;
+        muted: (s: string) => string;
+    }): string;
+    /**
+     * Render tabs with custom separator.
+     *
+     * @param state - State containing currentTab
+     * @param styles - Theme styles
+     * @param separator - Separator between tabs (default: '')
+     * @returns Rendered tab bar string
+     */
+    renderTabsWithSeparator(state: TabState, styles: {
+        selected: (s: string) => string;
+        muted: (s: string) => string;
+    }, separator?: string): string;
+    /**
+     * Render keyboard hints for tabs.
+     *
+     * @returns Hint string like "Tab Switch · 1-5 Jump"
+     */
+    renderHints(): string;
+    /**
+     * Get the current tab definition.
+     *
+     * @param state - State containing currentTab
+     * @returns Current tab or undefined
+     */
+    getCurrentTab(state: TabState): TabDefinition | undefined;
+    /**
+     * Get the current tab ID.
+     *
+     * @param state - State containing currentTab
+     * @returns Current tab ID or empty string
+     */
+    getCurrentTabId(state: TabState): string;
+    /**
+     * Get the number of tabs.
+     */
+    getTabCount(): number;
+    /**
+     * Find tab index by ID.
+     *
+     * @param tabId - Tab ID to find
+     * @returns Index or -1 if not found
+     */
+    findTabIndex(tabId: string): number;
+    /**
+     * Set current tab by ID.
+     *
+     * @param state - State to modify
+     * @param tabId - Tab ID to select
+     * @returns true if tab was found and selected
+     */
+    setTabById(state: TabState, tabId: string): boolean;
+    private notifyChange;
+}
+/**
+ * Create tab definitions from an array of strings.
+ * IDs are lowercase versions of labels.
+ *
+ * @param labels - Tab labels
+ * @returns Tab definitions
+ */
+export declare function createTabsFromLabels(labels: string[]): TabDefinition[];
+/**
+ * Create filter tabs (common pattern).
+ *
+ * @param filters - Array of filter names
+ * @returns Tab definitions with 'all' as first tab
+ */
+export declare function createFilterTabs(filters: string[]): TabDefinition[];

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

@@ -0,0 +1,307 @@
+/**
+ * Tab Feature
+ *
+ * Composable feature for tab/filter navigation.
+ * Handles Tab/Shift+Tab and number keys for tab switching.
+ *
+ * Note: Arrow keys (←→/hl) are NOT used for tabs - they are reserved
+ * for page navigation in paginated overlays. This ensures consistent
+ * keyboard behavior across all overlays.
+ *
+ * Usage:
+ * ```typescript
+ * const TABS = [
+ *   { id: 'all', label: 'All' },
+ *   { id: 'active', label: 'Active' },
+ *   { id: 'completed', label: 'Completed' },
+ * ];
+ *
+ * interface MyState extends OverlayState, TabState {
+ *   // ...
+ * }
+ *
+ * class MyOverlay extends BaseOverlay<MyState, void> {
+ *   private tabFeature = new TabFeature(TABS, (tabId) => {
+ *     this.onTabChange(tabId);
+ *   });
+ *
+ *   handleKey(data: Buffer): void {
+ *     const result = this.tabFeature.handleKey(data, this.state);
+ *     if (result?.handled) {
+ *       if (result.action === 'render') this.update();
+ *       return;
+ *     }
+ *     // ... other key handling
+ *   }
+ *
+ *   render(): string[] {
+ *     return [
+ *       ...this.renderHeader('My Overlay'),
+ *       ' ' + this.tabFeature.renderTabs(this.state, this.styles),
+ *       '',
+ *       // ... content
+ *       ...this.renderFooter(this.tabFeature.renderHints() + ' · ↑↓/jk Navigate')
+ *     ];
+ *   }
+ * }
+ * ```
+ */
+import { isTab, isShiftTab, getNumberKey, } from '../base/key-utils.js';
+// =============================================================================
+// TabFeature Class
+// =============================================================================
+/**
+ * Feature for tab/filter navigation.
+ *
+ * Handles:
+ * - Tab/Shift+Tab for cycling tabs
+ * - Number keys 1-9 for direct selection (optional)
+ *
+ * Note: Arrow keys are NOT handled - they are reserved for pagination.
+ */
+export class TabFeature {
+    config;
+    /**
+     * Create a new TabFeature.
+     *
+     * @param tabs - Tab definitions
+     * @param onChange - Optional callback when tab changes
+     */
+    constructor(tabs, onChange) {
+        this.config = {
+            tabs,
+            onChange,
+            useNumberKeys: tabs.length <= 9,
+            wrapNavigation: true,
+        };
+    }
+    /**
+     * Create from config object (alternative constructor).
+     */
+    static fromConfig(config) {
+        const feature = new TabFeature(config.tabs, config.onChange);
+        if (config.useNumberKeys !== undefined) {
+            feature.config.useNumberKeys = config.useNumberKeys;
+        }
+        if (config.wrapNavigation !== undefined) {
+            feature.config.wrapNavigation = config.wrapNavigation;
+        }
+        return feature;
+    }
+    // ===========================================================================
+    // Key Handling
+    // ===========================================================================
+    /**
+     * Handle a key press.
+     *
+     * @param data - Raw key buffer
+     * @param state - State containing currentTab
+     * @returns KeyResult if handled, null otherwise
+     */
+    handleKey(data, state) {
+        const tabCount = this.config.tabs.length;
+        if (tabCount === 0) {
+            return null; // No tabs
+        }
+        // Tab - next tab
+        if (isTab(data)) {
+            const newIndex = this.config.wrapNavigation
+                ? (state.currentTab + 1) % tabCount
+                : Math.min(state.currentTab + 1, tabCount - 1);
+            if (newIndex !== state.currentTab) {
+                state.currentTab = newIndex;
+                this.notifyChange(state);
+                return { handled: true, action: 'render' };
+            }
+            return { handled: true }; // At end, consume but no change
+        }
+        // Shift+Tab - previous tab
+        if (isShiftTab(data)) {
+            const newIndex = this.config.wrapNavigation
+                ? (state.currentTab - 1 + tabCount) % tabCount
+                : Math.max(state.currentTab - 1, 0);
+            if (newIndex !== state.currentTab) {
+                state.currentTab = newIndex;
+                this.notifyChange(state);
+                return { handled: true, action: 'render' };
+            }
+            return { handled: true }; // At start, consume but no change
+        }
+        // Number keys 1-9 for direct selection
+        if (this.config.useNumberKeys) {
+            const num = getNumberKey(data);
+            if (num !== null && num >= 1 && num <= tabCount) {
+                const newIndex = num - 1;
+                if (newIndex !== state.currentTab) {
+                    state.currentTab = newIndex;
+                    this.notifyChange(state);
+                    return { handled: true, action: 'render' };
+                }
+                return { handled: true }; // Already on this tab
+            }
+        }
+        return null; // Not handled
+    }
+    // ===========================================================================
+    // Rendering
+    // ===========================================================================
+    /**
+     * Render tabs in a row.
+     *
+     * @param state - State containing currentTab
+     * @param styles - Theme styles
+     * @returns Rendered tab bar string
+     */
+    renderTabs(state, styles) {
+        return this.config.tabs
+            .map((tab, index) => {
+            const label = ` ${tab.label} `;
+            return index === state.currentTab
+                ? styles.selected(label)
+                : styles.muted(label);
+        })
+            .join('');
+    }
+    /**
+     * Render tabs with number key hints.
+     *
+     * @param state - State containing currentTab
+     * @param styles - Theme styles
+     * @returns Rendered tab bar string with numbers
+     */
+    renderTabsWithNumbers(state, styles) {
+        return this.config.tabs
+            .map((tab, index) => {
+            const num = String(index + 1);
+            const label = ` ${num}:${tab.label} `;
+            return index === state.currentTab
+                ? styles.selected(label)
+                : styles.muted(label);
+        })
+            .join('');
+    }
+    /**
+     * Render tabs with custom separator.
+     *
+     * @param state - State containing currentTab
+     * @param styles - Theme styles
+     * @param separator - Separator between tabs (default: '')
+     * @returns Rendered tab bar string
+     */
+    renderTabsWithSeparator(state, styles, separator = '') {
+        return this.config.tabs
+            .map((tab, index) => {
+            const label = ` ${tab.label} `;
+            return index === state.currentTab
+                ? styles.selected(label)
+                : styles.muted(label);
+        })
+            .join(separator);
+    }
+    /**
+     * Render keyboard hints for tabs.
+     *
+     * @returns Hint string like "Tab Switch · 1-5 Jump"
+     */
+    renderHints() {
+        const tabCount = this.config.tabs.length;
+        if (tabCount === 0) {
+            return '';
+        }
+        if (this.config.useNumberKeys && tabCount <= 9) {
+            return `Tab Switch · 1-${String(tabCount)} Jump`;
+        }
+        return 'Tab Switch';
+    }
+    // ===========================================================================
+    // Utilities
+    // ===========================================================================
+    /**
+     * Get the current tab definition.
+     *
+     * @param state - State containing currentTab
+     * @returns Current tab or undefined
+     */
+    getCurrentTab(state) {
+        return this.config.tabs[state.currentTab];
+    }
+    /**
+     * Get the current tab ID.
+     *
+     * @param state - State containing currentTab
+     * @returns Current tab ID or empty string
+     */
+    getCurrentTabId(state) {
+        return this.config.tabs[state.currentTab]?.id ?? '';
+    }
+    /**
+     * Get the number of tabs.
+     */
+    getTabCount() {
+        return this.config.tabs.length;
+    }
+    /**
+     * Find tab index by ID.
+     *
+     * @param tabId - Tab ID to find
+     * @returns Index or -1 if not found
+     */
+    findTabIndex(tabId) {
+        return this.config.tabs.findIndex((t) => t.id === tabId);
+    }
+    /**
+     * Set current tab by ID.
+     *
+     * @param state - State to modify
+     * @param tabId - Tab ID to select
+     * @returns true if tab was found and selected
+     */
+    setTabById(state, tabId) {
+        const index = this.findTabIndex(tabId);
+        if (index >= 0) {
+            state.currentTab = index;
+            return true;
+        }
+        return false;
+    }
+    // ===========================================================================
+    // Private Methods
+    // ===========================================================================
+    notifyChange(state) {
+        if (this.config.onChange) {
+            const tab = this.config.tabs[state.currentTab];
+            this.config.onChange(tab.id, state.currentTab);
+        }
+    }
+}
+// =============================================================================
+// Helper Functions
+// =============================================================================
+/**
+ * Create tab definitions from an array of strings.
+ * IDs are lowercase versions of labels.
+ *
+ * @param labels - Tab labels
+ * @returns Tab definitions
+ */
+export function createTabsFromLabels(labels) {
+    return labels.map((label) => ({
+        id: label.toLowerCase().replace(/\s+/g, '-'),
+        label,
+    }));
+}
+/**
+ * Create filter tabs (common pattern).
+ *
+ * @param filters - Array of filter names
+ * @returns Tab definitions with 'all' as first tab
+ */
+export function createFilterTabs(filters) {
+    return [
+        { id: 'all', label: 'All' },
+        ...filters.map((f) => ({
+            id: f.toLowerCase().replace(/\s+/g, '-'),
+            label: f,
+        })),
+    ];
+}