@compilr-dev/cli 0.4.0 → 0.5.0

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

@@ -0,0 +1,238 @@
+/**
+ * Input Feature
+ *
+ * Composable text input handling for overlays.
+ * Provides cursor movement, text editing, and rendering.
+ *
+ * Usage:
+ * ```typescript
+ * class MyScreen extends BaseScreen {
+ *   private input = new InputFeature({ placeholder: 'Enter text...' });
+ *
+ *   render(): string[] {
+ *     return [
+ *       ' ' + this.input.render(styles),
+ *     ];
+ *   }
+ *
+ *   handleKey(data: Buffer): ScreenResult {
+ *     const result = this.input.handleKey(data);
+ *     if (result.handled) {
+ *       return stay();
+ *     }
+ *     // Handle other keys (Enter, Escape, etc.)
+ *   }
+ * }
+ * ```
+ */
+import { isLeftArrow, isRightArrow, isBackspace, isDelete, isHome, isEnd, isCtrlA, isCtrlE, isWordLeft, isWordRight, extractPrintable, } from '../base/key-utils.js';
+// =============================================================================
+// InputFeature Class
+// =============================================================================
+export class InputFeature {
+    /** Current text value */
+    _value;
+    /** Cursor position (0 = before first char, value.length = after last char) */
+    _cursor;
+    /** Placeholder text */
+    placeholder;
+    /** Maximum length */
+    maxLength;
+    constructor(options = {}) {
+        this._value = options.initialValue ?? '';
+        this._cursor = this._value.length;
+        this.placeholder = options.placeholder ?? '';
+        this.maxLength = options.maxLength ?? 0;
+    }
+    // ===========================================================================
+    // Getters/Setters
+    // ===========================================================================
+    /** Get current value */
+    get value() {
+        return this._value;
+    }
+    /** Set value (resets cursor to end) */
+    set value(v) {
+        this._value = v;
+        this._cursor = v.length;
+    }
+    /** Get cursor position */
+    get cursor() {
+        return this._cursor;
+    }
+    /** Check if empty */
+    get isEmpty() {
+        return this._value.length === 0;
+    }
+    /** Get trimmed value */
+    get trimmedValue() {
+        return this._value.trim();
+    }
+    // ===========================================================================
+    // Key Handling
+    // ===========================================================================
+    /**
+     * Handle a key press.
+     * Returns whether the key was handled and whether to re-render.
+     */
+    handleKey(data) {
+        // Left arrow - move cursor left
+        if (isLeftArrow(data)) {
+            if (this._cursor > 0) {
+                this._cursor--;
+                return { handled: true, render: true };
+            }
+            return { handled: true, render: false };
+        }
+        // Right arrow - move cursor right
+        if (isRightArrow(data)) {
+            if (this._cursor < this._value.length) {
+                this._cursor++;
+                return { handled: true, render: true };
+            }
+            return { handled: true, render: false };
+        }
+        // Home or Ctrl+A - move to start
+        if (isHome(data) || isCtrlA(data)) {
+            if (this._cursor > 0) {
+                this._cursor = 0;
+                return { handled: true, render: true };
+            }
+            return { handled: true, render: false };
+        }
+        // End or Ctrl+E - move to end
+        if (isEnd(data) || isCtrlE(data)) {
+            if (this._cursor < this._value.length) {
+                this._cursor = this._value.length;
+                return { handled: true, render: true };
+            }
+            return { handled: true, render: false };
+        }
+        // Word left (Ctrl+Left, Alt+b)
+        if (isWordLeft(data)) {
+            const newPos = this.findWordBoundaryLeft();
+            if (newPos !== this._cursor) {
+                this._cursor = newPos;
+                return { handled: true, render: true };
+            }
+            return { handled: true, render: false };
+        }
+        // Word right (Ctrl+Right, Alt+f)
+        if (isWordRight(data)) {
+            const newPos = this.findWordBoundaryRight();
+            if (newPos !== this._cursor) {
+                this._cursor = newPos;
+                return { handled: true, render: true };
+            }
+            return { handled: true, render: false };
+        }
+        // Backspace - delete before cursor
+        if (isBackspace(data)) {
+            if (this._cursor > 0) {
+                this._value =
+                    this._value.slice(0, this._cursor - 1) + this._value.slice(this._cursor);
+                this._cursor--;
+                return { handled: true, render: true };
+            }
+            return { handled: true, render: false };
+        }
+        // Delete - delete at cursor
+        if (isDelete(data)) {
+            if (this._cursor < this._value.length) {
+                this._value =
+                    this._value.slice(0, this._cursor) + this._value.slice(this._cursor + 1);
+                return { handled: true, render: true };
+            }
+            return { handled: true, render: false };
+        }
+        // Printable characters - insert at cursor
+        const printable = extractPrintable(data);
+        if (printable.length > 0) {
+            // Check max length
+            if (this.maxLength > 0 && this._value.length + printable.length > this.maxLength) {
+                const allowed = this.maxLength - this._value.length;
+                if (allowed <= 0) {
+                    return { handled: true, render: false };
+                }
+                const truncated = printable.slice(0, allowed);
+                this._value =
+                    this._value.slice(0, this._cursor) + truncated + this._value.slice(this._cursor);
+                this._cursor += truncated.length;
+                return { handled: true, render: true };
+            }
+            this._value =
+                this._value.slice(0, this._cursor) + printable + this._value.slice(this._cursor);
+            this._cursor += printable.length;
+            return { handled: true, render: true };
+        }
+        // Not handled
+        return { handled: false, render: false };
+    }
+    // ===========================================================================
+    // Rendering
+    // ===========================================================================
+    /**
+     * Render the input field with cursor.
+     * Returns a string like: "> text with cursor_"
+     *
+     * @param styles - Theme styles for coloring
+     * @param prefix - Prefix before the input (default: "> ")
+     */
+    render(styles, prefix = '> ') {
+        if (this._value.length === 0 && this.placeholder) {
+            // Show placeholder with cursor at start
+            return styles.primary(prefix) + styles.primary('▋') + styles.muted(this.placeholder);
+        }
+        // Split text at cursor position
+        const before = this._value.slice(0, this._cursor);
+        const after = this._value.slice(this._cursor);
+        return styles.primary(prefix) + before + styles.primary('▋') + after;
+    }
+    /**
+     * Render input field without cursor (for non-focused state).
+     */
+    renderWithoutCursor(styles, prefix = '> ') {
+        if (this._value.length === 0 && this.placeholder) {
+            return styles.muted(prefix + this.placeholder);
+        }
+        return prefix + this._value;
+    }
+    // ===========================================================================
+    // Helpers
+    // ===========================================================================
+    /** Clear the input */
+    clear() {
+        this._value = '';
+        this._cursor = 0;
+    }
+    /** Find word boundary to the left of cursor */
+    findWordBoundaryLeft() {
+        if (this._cursor === 0)
+            return 0;
+        let pos = this._cursor - 1;
+        // Skip whitespace
+        while (pos > 0 && /\s/.test(this._value[pos])) {
+            pos--;
+        }
+        // Skip word characters
+        while (pos > 0 && !/\s/.test(this._value[pos - 1])) {
+            pos--;
+        }
+        return pos;
+    }
+    /** Find word boundary to the right of cursor */
+    findWordBoundaryRight() {
+        if (this._cursor >= this._value.length)
+            return this._value.length;
+        let pos = this._cursor;
+        // Skip current word
+        while (pos < this._value.length && !/\s/.test(this._value[pos])) {
+            pos++;
+        }
+        // Skip whitespace
+        while (pos < this._value.length && /\s/.test(this._value[pos])) {
+            pos++;
+        }
+        return pos;
+    }
+}

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