@compilr-dev/cli 0.4.0 → 0.5.1

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

@@ -0,0 +1,155 @@
+/**
+ * List Feature
+ *
+ * Composable feature for list selection and navigation.
+ * Handles up/down navigation, selection, and rendering.
+ *
+ * Usage:
+ * ```typescript
+ * interface MyState extends OverlayState, ListState {
+ *   items: string[];
+ * }
+ *
+ * class MyOverlay extends BaseOverlay<MyState, string | null> {
+ *   private listFeature = new ListFeature<string>(
+ *     () => this.state.items,
+ *     (item) => this.onSelect(item)
+ *   );
+ *
+ *   handleKey(data: Buffer): void {
+ *     const result = this.listFeature.handleKey(data, this.state);
+ *     if (result?.handled) {
+ *       if (result.action === 'render') this.update();
+ *       return;
+ *     }
+ *     // ... other key handling
+ *   }
+ *
+ *   render(): string[] {
+ *     return [
+ *       ...this.renderHeader('Select Item'),
+ *       ...this.listFeature.renderItems(this.state, (opts) => {
+ *         const prefix = opts.isSelected ? ' > ' : '   ';
+ *         return opts.isSelected
+ *           ? this.styles.primary(`${prefix}${opts.item}`)
+ *           : this.styles.muted(`${prefix}${opts.item}`);
+ *       }),
+ *       ...this.renderFooter('↑↓/jk Navigate · Enter Select')
+ *     ];
+ *   }
+ * }
+ * ```
+ */
+import type { KeyResult, ListState, ListItemRenderer } from '../base/overlay-types.js';
+/**
+ * Configuration for ListFeature.
+ */
+export interface ListFeatureConfig<T> {
+    /**
+     * Function to get the current list of items.
+     * Called each time keys are handled or items are rendered.
+     */
+    getItems: () => T[];
+    /**
+     * Optional callback when an item is selected (Enter pressed).
+     * If not provided, Enter key is not handled by this feature.
+     */
+    onSelect?: (item: T, index: number) => void;
+    /**
+     * Whether to wrap navigation at boundaries.
+     * If true, navigating up from first item goes to last, and vice versa.
+     * Default: false
+     */
+    wrapNavigation?: boolean;
+}
+/**
+ * Feature for list selection and navigation.
+ *
+ * Handles:
+ * - Up/Down arrows and j/k for navigation
+ * - Enter for selection (if onSelect provided)
+ *
+ * @template T - Type of items in the list
+ */
+export declare class ListFeature<T> {
+    private readonly config;
+    /**
+     * Create a new ListFeature.
+     *
+     * @param getItems - Function to get current items
+     * @param onSelect - Optional callback for selection
+     */
+    constructor(getItems: () => T[], onSelect?: (item: T, index: number) => void);
+    /**
+     * Create from config object (alternative constructor).
+     */
+    static fromConfig<T>(config: ListFeatureConfig<T>): ListFeature<T>;
+    /**
+     * Handle a key press.
+     *
+     * @param data - Raw key buffer
+     * @param state - State containing selectedIndex
+     * @returns KeyResult if handled, null otherwise
+     */
+    handleKey(data: Buffer, state: ListState): KeyResult | null;
+    /**
+     * Render list items using a custom renderer.
+     *
+     * @param state - State containing selectedIndex
+     * @param renderer - Function to render each item
+     * @returns Array of rendered lines
+     */
+    renderItems(state: ListState, renderer: ListItemRenderer<T>): string[];
+    /**
+     * Render a subset of items (for pagination).
+     *
+     * @param state - State containing selectedIndex
+     * @param startIndex - First item index to render
+     * @param count - Number of items to render
+     * @param renderer - Function to render each item
+     * @returns Array of rendered lines
+     */
+    renderItemsSlice(state: ListState, startIndex: number, count: number, renderer: ListItemRenderer<T>): string[];
+    /**
+     * Get the currently selected item.
+     *
+     * @param state - State containing selectedIndex
+     * @returns Selected item or undefined if out of bounds
+     */
+    getSelectedItem(state: ListState): T | undefined;
+    /**
+     * Get the total number of items.
+     */
+    getItemCount(): number;
+    /**
+     * Ensure selectedIndex is within bounds.
+     * Call this after items change.
+     *
+     * @param state - State to adjust
+     */
+    clampSelection(state: ListState): void;
+}
+/**
+ * Create a simple list renderer with standard styling.
+ *
+ * @param styles - Theme styles object
+ * @param getLabel - Function to get display label from item
+ * @returns Renderer function
+ */
+export declare function createSimpleListRenderer<T>(styles: {
+    primary: (s: string) => string;
+    muted: (s: string) => string;
+}, getLabel: (item: T) => string): ListItemRenderer<T>;
+/**
+ * Create a list renderer with label and description.
+ *
+ * @param styles - Theme styles object
+ * @param getLabel - Function to get display label
+ * @param getDescription - Function to get description
+ * @param labelWidth - Fixed width for label column (for alignment)
+ * @returns Renderer function
+ */
+export declare function createLabelDescriptionRenderer<T>(styles: {
+    primary: (s: string) => string;
+    muted: (s: string) => string;
+}, getLabel: (item: T) => string, getDescription: (item: T) => string, labelWidth?: number): ListItemRenderer<T>;

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

@@ -0,0 +1,244 @@
+/**
+ * List Feature
+ *
+ * Composable feature for list selection and navigation.
+ * Handles up/down navigation, selection, and rendering.
+ *
+ * Usage:
+ * ```typescript
+ * interface MyState extends OverlayState, ListState {
+ *   items: string[];
+ * }
+ *
+ * class MyOverlay extends BaseOverlay<MyState, string | null> {
+ *   private listFeature = new ListFeature<string>(
+ *     () => this.state.items,
+ *     (item) => this.onSelect(item)
+ *   );
+ *
+ *   handleKey(data: Buffer): void {
+ *     const result = this.listFeature.handleKey(data, this.state);
+ *     if (result?.handled) {
+ *       if (result.action === 'render') this.update();
+ *       return;
+ *     }
+ *     // ... other key handling
+ *   }
+ *
+ *   render(): string[] {
+ *     return [
+ *       ...this.renderHeader('Select Item'),
+ *       ...this.listFeature.renderItems(this.state, (opts) => {
+ *         const prefix = opts.isSelected ? ' > ' : '   ';
+ *         return opts.isSelected
+ *           ? this.styles.primary(`${prefix}${opts.item}`)
+ *           : this.styles.muted(`${prefix}${opts.item}`);
+ *       }),
+ *       ...this.renderFooter('↑↓/jk Navigate · Enter Select')
+ *     ];
+ *   }
+ * }
+ * ```
+ */
+import { isNavigateUp, isNavigateDown, isEnter, } from '../base/key-utils.js';
+// =============================================================================
+// ListFeature Class
+// =============================================================================
+/**
+ * Feature for list selection and navigation.
+ *
+ * Handles:
+ * - Up/Down arrows and j/k for navigation
+ * - Enter for selection (if onSelect provided)
+ *
+ * @template T - Type of items in the list
+ */
+export class ListFeature {
+    config;
+    /**
+     * Create a new ListFeature.
+     *
+     * @param getItems - Function to get current items
+     * @param onSelect - Optional callback for selection
+     */
+    constructor(getItems, onSelect) {
+        this.config = { getItems, onSelect };
+    }
+    /**
+     * Create from config object (alternative constructor).
+     */
+    static fromConfig(config) {
+        const feature = new ListFeature(config.getItems, config.onSelect);
+        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 selectedIndex
+     * @returns KeyResult if handled, null otherwise
+     */
+    handleKey(data, state) {
+        const items = this.config.getItems();
+        const itemCount = items.length;
+        if (itemCount === 0) {
+            return null; // Nothing to navigate
+        }
+        // Navigate up
+        if (isNavigateUp(data)) {
+            if (state.selectedIndex > 0) {
+                state.selectedIndex--;
+                return { handled: true, action: 'render' };
+            }
+            else if (this.config.wrapNavigation) {
+                state.selectedIndex = itemCount - 1;
+                return { handled: true, action: 'render' };
+            }
+            return { handled: true }; // At top, consume but no change
+        }
+        // Navigate down
+        if (isNavigateDown(data)) {
+            if (state.selectedIndex < itemCount - 1) {
+                state.selectedIndex++;
+                return { handled: true, action: 'render' };
+            }
+            else if (this.config.wrapNavigation) {
+                state.selectedIndex = 0;
+                return { handled: true, action: 'render' };
+            }
+            return { handled: true }; // At bottom, consume but no change
+        }
+        // Select (Enter)
+        if (isEnter(data) && this.config.onSelect) {
+            const item = items[state.selectedIndex];
+            if (item !== undefined) {
+                this.config.onSelect(item, state.selectedIndex);
+                return { handled: true };
+            }
+        }
+        return null; // Not handled
+    }
+    // ===========================================================================
+    // Rendering
+    // ===========================================================================
+    /**
+     * Render list items using a custom renderer.
+     *
+     * @param state - State containing selectedIndex
+     * @param renderer - Function to render each item
+     * @returns Array of rendered lines
+     */
+    renderItems(state, renderer) {
+        const items = this.config.getItems();
+        return items.map((item, index) => renderer({
+            item,
+            isSelected: index === state.selectedIndex,
+            index,
+        }));
+    }
+    /**
+     * Render a subset of items (for pagination).
+     *
+     * @param state - State containing selectedIndex
+     * @param startIndex - First item index to render
+     * @param count - Number of items to render
+     * @param renderer - Function to render each item
+     * @returns Array of rendered lines
+     */
+    renderItemsSlice(state, startIndex, count, renderer) {
+        const items = this.config.getItems();
+        const endIndex = Math.min(startIndex + count, items.length);
+        const lines = [];
+        for (let i = startIndex; i < endIndex; i++) {
+            const item = items[i];
+            lines.push(renderer({
+                item,
+                isSelected: i === state.selectedIndex,
+                index: i,
+            }));
+        }
+        return lines;
+    }
+    // ===========================================================================
+    // Utilities
+    // ===========================================================================
+    /**
+     * Get the currently selected item.
+     *
+     * @param state - State containing selectedIndex
+     * @returns Selected item or undefined if out of bounds
+     */
+    getSelectedItem(state) {
+        const items = this.config.getItems();
+        return items[state.selectedIndex];
+    }
+    /**
+     * Get the total number of items.
+     */
+    getItemCount() {
+        return this.config.getItems().length;
+    }
+    /**
+     * Ensure selectedIndex is within bounds.
+     * Call this after items change.
+     *
+     * @param state - State to adjust
+     */
+    clampSelection(state) {
+        const itemCount = this.getItemCount();
+        if (itemCount === 0) {
+            state.selectedIndex = 0;
+        }
+        else if (state.selectedIndex >= itemCount) {
+            state.selectedIndex = itemCount - 1;
+        }
+        else if (state.selectedIndex < 0) {
+            state.selectedIndex = 0;
+        }
+    }
+}
+// =============================================================================
+// Helper Functions
+// =============================================================================
+/**
+ * Create a simple list renderer with standard styling.
+ *
+ * @param styles - Theme styles object
+ * @param getLabel - Function to get display label from item
+ * @returns Renderer function
+ */
+export function createSimpleListRenderer(styles, getLabel) {
+    return ({ item, isSelected }) => {
+        const prefix = isSelected ? ' > ' : '   ';
+        const label = getLabel(item);
+        return isSelected
+            ? styles.primary(`${prefix}${label}`)
+            : styles.muted(`${prefix}${label}`);
+    };
+}
+/**
+ * Create a list renderer with label and description.
+ *
+ * @param styles - Theme styles object
+ * @param getLabel - Function to get display label
+ * @param getDescription - Function to get description
+ * @param labelWidth - Fixed width for label column (for alignment)
+ * @returns Renderer function
+ */
+export function createLabelDescriptionRenderer(styles, getLabel, getDescription, labelWidth = 20) {
+    return ({ item, isSelected }) => {
+        const prefix = isSelected ? ' > ' : '   ';
+        const label = getLabel(item).padEnd(labelWidth);
+        const desc = getDescription(item);
+        if (isSelected) {
+            return styles.primary(`${prefix}${label}`) + styles.muted(desc);
+        }
+        return styles.muted(`${prefix}${label}${desc}`);
+    };
+}

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