@oh-my-pi/pi-tui 15.1.1 → 15.1.2

package/dist/types/autocomplete.d.ts

@@ -0,0 +1,64 @@
+export interface AutocompleteItem {
+    value: string;
+    label: string;
+    description?: string;
+    /** Dim hint text shown inline after cursor when this item is selected */
+    hint?: string;
+}
+type Awaitable<T> = T | Promise<T>;
+export interface SlashCommand {
+    name: string;
+    description?: string;
+    argumentHint?: string;
+    getArgumentCompletions?(argumentPrefix: string): Awaitable<AutocompleteItem[] | null>;
+    /** Return inline hint text for the current argument state (shown as dim ghost text after cursor) */
+    getInlineHint?(argumentText: string): string | null;
+}
+export interface AutocompleteProvider {
+    /** Get autocomplete suggestions for current text/cursor position */
+    getSuggestions(lines: string[], cursorLine: number, cursorCol: number): Promise<{
+        items: AutocompleteItem[];
+        prefix: string;
+    } | null>;
+    /** Apply the selected item and return new text + cursor position */
+    applyCompletion(lines: string[], cursorLine: number, cursorCol: number, item: AutocompleteItem, prefix: string): {
+        lines: string[];
+        cursorLine: number;
+        cursorCol: number;
+        onApplied?: () => void;
+    };
+    /** Get inline hint text to show as dim ghost text after the cursor */
+    getInlineHint?(lines: string[], cursorLine: number, cursorCol: number): string | null;
+    /** Synchronously try to complete a slash command at the start of a line (no async I/O). */
+    /** Returns matched items and the full prefix, or null if not applicable. */
+    trySyncSlashCompletion?(textBeforeCursor: string): {
+        items: AutocompleteItem[];
+        prefix: string;
+    } | null;
+}
+export declare class CombinedAutocompleteProvider implements AutocompleteProvider {
+    #private;
+    constructor(commands?: (SlashCommand | AutocompleteItem)[], basePath?: string);
+    getSuggestions(lines: string[], cursorLine: number, cursorCol: number): Promise<{
+        items: AutocompleteItem[];
+        prefix: string;
+    } | null>;
+    applyCompletion(lines: string[], cursorLine: number, cursorCol: number, item: AutocompleteItem, prefix: string): {
+        lines: string[];
+        cursorLine: number;
+        cursorCol: number;
+    };
+    invalidateDirCache(dir?: string): void;
+    getForceFileSuggestions(lines: string[], cursorLine: number, cursorCol: number): Promise<{
+        items: AutocompleteItem[];
+        prefix: string;
+    } | null>;
+    shouldTriggerFileCompletion(lines: string[], cursorLine: number, cursorCol: number): boolean;
+    /** Get inline hint text for slash commands with subcommand hints */
+    getInlineHint(lines: string[], cursorLine: number, cursorCol: number): string | null;
+    trySyncSlashCompletion(textBeforeCursor: string): {
+        items: AutocompleteItem[];
+        prefix: string;
+    } | null;
+}
+export {};

package/dist/types/bracketed-paste.d.ts

@@ -0,0 +1,26 @@
+export type PasteResult = {
+    handled: false;
+} | {
+    handled: true;
+    pasteContent?: string;
+    remaining: string;
+};
+/**
+ * Handles bracketed paste mode buffering for terminal input components.
+ *
+ * Bracketed paste mode wraps pasted content between start (\x1b[200~) and
+ * end (\x1b[201~) markers, which may arrive split across multiple chunks.
+ * This class buffers incoming data and assembles complete paste payloads.
+ */
+export declare class BracketedPasteHandler {
+    #private;
+    /**
+     * Process incoming terminal data for bracketed paste sequences.
+     *
+     * @returns `{ handled: false }` if the data contains no paste sequence and
+     *          should be processed normally. `{ handled: true }` if the data was
+     *          consumed by paste buffering — `pasteContent` is set when a complete
+     *          paste has been assembled; omitted when still buffering.
+     */
+    process(data: string): PasteResult;
+}

package/dist/types/components/box.d.ts

@@ -0,0 +1,15 @@
+import type { Component } from "../tui";
+/**
+ * Box component - a container that applies padding and background to all children
+ */
+export declare class Box implements Component {
+    #private;
+    children: Component[];
+    constructor(paddingX?: number, paddingY?: number, bgFn?: (text: string) => string);
+    addChild(component: Component): void;
+    removeChild(component: Component): void;
+    clear(): void;
+    setBgFn(bgFn?: (text: string) => string): void;
+    invalidate(): void;
+    render(width: number): string[];
+}

package/dist/types/components/cancellable-loader.d.ts

@@ -0,0 +1,21 @@
+import { Loader } from "./loader";
+/**
+ * Loader that can be cancelled with Escape.
+ * Extends Loader with an AbortSignal for cancelling async operations.
+ *
+ * @example
+ * const loader = new CancellableLoader(tui, cyan, dim, "Working...");
+ * loader.onAbort = () => done(null);
+ * doWork(loader.signal).then(done);
+ */
+export declare class CancellableLoader extends Loader {
+    #private;
+    /** Called when user presses Escape */
+    onAbort?: () => void;
+    /** AbortSignal that is aborted when user presses Escape */
+    get signal(): AbortSignal;
+    /** Whether the loader was aborted */
+    get aborted(): boolean;
+    handleInput(data: string): void;
+    dispose(): void;
+}

package/dist/types/components/editor.d.ts

@@ -0,0 +1,101 @@
+import type { AutocompleteProvider } from "../autocomplete";
+import type { SymbolTheme } from "../symbols";
+import { type Component, type Focusable } from "../tui";
+import { type SelectListTheme } from "./select-list";
+export interface EditorTheme {
+    borderColor: (str: string) => string;
+    selectList: SelectListTheme;
+    symbols: SymbolTheme;
+    editorPaddingX?: number;
+    /** Style function for inline hint/ghost text (dim text after cursor) */
+    hintStyle?: (text: string) => string;
+}
+export interface EditorTopBorder {
+    /** The status content (already styled) */
+    content: string;
+    /** Visible width of the content */
+    width: number;
+}
+interface HistoryEntry {
+    prompt: string;
+}
+interface HistoryStorage {
+    add(prompt: string, cwd?: string): Promise<void>;
+    getRecent(limit: number): HistoryEntry[];
+}
+export declare class Editor implements Component, Focusable {
+    #private;
+    /** Focusable interface - set by TUI when focus changes */
+    focused: boolean;
+    /** When set, replaces the normal cursor glyph at end-of-text with this ANSI-styled string. */
+    cursorOverride: string | undefined;
+    /** Display width of the cursorOverride glyph (needed because override may contain ANSI escapes). */
+    cursorOverrideWidth: number | undefined;
+    borderColor: (str: string) => string;
+    onAutocompleteUpdate?: () => void;
+    onSubmit?: (text: string) => void;
+    onAltEnter?: (text: string) => void;
+    onChange?: (text: string) => void;
+    onAutocompleteCancel?: () => void;
+    disableSubmit: boolean;
+    constructor(theme: EditorTheme);
+    setAutocompleteProvider(provider: AutocompleteProvider): void;
+    /**
+     * Set custom content for the top border (e.g., status line).
+     * Pass undefined to use the default plain border.
+     */
+    setTopBorder(content: EditorTopBorder | undefined): void;
+    /**
+     * Show or hide the editor border chrome.
+     */
+    setBorderVisible(borderVisible: boolean): void;
+    setPromptGutter(promptGutter: string | undefined): void;
+    /**
+     * Get the available width for top border content given a total terminal width.
+     * Accounts for the border characters and horizontal padding when visible.
+     */
+    getTopBorderAvailableWidth(terminalWidth: number): number;
+    /**
+     * Use the real terminal cursor instead of rendering a cursor glyph.
+     */
+    setUseTerminalCursor(useTerminalCursor: boolean): void;
+    getUseTerminalCursor(): boolean;
+    setMaxHeight(maxHeight: number | undefined): void;
+    setPaddingX(paddingX: number): void;
+    getAutocompleteMaxVisible(): number;
+    setAutocompleteMaxVisible(maxVisible: number): void;
+    setHistoryStorage(storage: HistoryStorage): void;
+    /**
+     * Add a prompt to history for up/down arrow navigation.
+     * Called after successful submission.
+     */
+    addToHistory(text: string): void;
+    invalidate(): void;
+    render(width: number): string[];
+    handleInput(data: string): void;
+    getText(): string;
+    /**
+     * Get text with paste markers expanded to their actual content.
+     * Use this when you need the full content (e.g., for external editor).
+     */
+    getExpandedText(): string;
+    getLines(): string[];
+    getCursor(): {
+        line: number;
+        col: number;
+    };
+    moveToLineStart(): void;
+    moveToLineEnd(): void;
+    moveToMessageStart(): void;
+    moveToMessageEnd(): void;
+    /**
+     * Undo the last meaningful edit while ignoring transient text that is still present at the cursor.
+     * Used for command-like autocomplete actions whose typed trigger should not count as the edit being undone.
+     */
+    undoPastTransientText(transientText: string): void;
+    setText(text: string): void;
+    /** Insert text at the current cursor position */
+    insertText(text: string): void;
+    isShowingAutocomplete(): boolean;
+}
+export {};

package/dist/types/components/image.d.ts

@@ -0,0 +1,16 @@
+import { type ImageDimensions } from "../terminal-capabilities";
+import type { Component } from "../tui";
+export interface ImageTheme {
+    fallbackColor: (str: string) => string;
+}
+export interface ImageOptions {
+    maxWidthCells?: number;
+    maxHeightCells?: number;
+    filename?: string;
+}
+export declare class Image implements Component {
+    #private;
+    constructor(base64Data: string, mimeType: string, theme: ImageTheme, options?: ImageOptions, dimensions?: ImageDimensions);
+    invalidate(): void;
+    render(width: number): string[];
+}

package/dist/types/components/input.d.ts

@@ -0,0 +1,16 @@
+import { type Component, type Focusable } from "../tui";
+/**
+ * Input component - single-line text input with horizontal scrolling
+ */
+export declare class Input implements Component, Focusable {
+    #private;
+    onSubmit?: (value: string) => void;
+    onEscape?: () => void;
+    /** Focusable interface - set by TUI when focus changes */
+    focused: boolean;
+    getValue(): string;
+    setValue(value: string): void;
+    handleInput(data: string): void;
+    invalidate(): void;
+    render(width: number): string[];
+}

package/dist/types/components/loader.d.ts

@@ -0,0 +1,16 @@
+import type { TUI } from "../tui";
+import { Text } from "./text";
+/**
+ * Loader component that updates every 80ms with spinning animation
+ */
+export declare class Loader extends Text {
+    #private;
+    private spinnerColorFn;
+    private messageColorFn;
+    private message;
+    constructor(ui: TUI, spinnerColorFn: (str: string) => string, messageColorFn: (str: string) => string, message?: string, spinnerFrames?: string[]);
+    render(width: number): string[];
+    start(): void;
+    stop(): void;
+    setMessage(message: string): void;
+}

package/dist/types/components/markdown.d.ts

@@ -0,0 +1,61 @@
+import type { SymbolTheme } from "../symbols";
+import type { Component } from "../tui";
+/** Drop all L2 cache entries. Call on theme change to prevent stale styled output. */
+export declare function clearRenderCache(): void;
+/**
+ * Default text styling for markdown content.
+ * Applied to all text unless overridden by markdown formatting.
+ */
+export interface DefaultTextStyle {
+    /** Foreground color function */
+    color?: (text: string) => string;
+    /** Background color function */
+    bgColor?: (text: string) => string;
+    /** Bold text */
+    bold?: boolean;
+    /** Italic text */
+    italic?: boolean;
+    /** Strikethrough text */
+    strikethrough?: boolean;
+    /** Underline text */
+    underline?: boolean;
+}
+/**
+ * Theme functions for markdown elements.
+ * Each function takes text and returns styled text with ANSI codes.
+ */
+export interface MarkdownTheme {
+    heading: (text: string) => string;
+    link: (text: string) => string;
+    linkUrl: (text: string) => string;
+    code: (text: string) => string;
+    codeBlock: (text: string) => string;
+    codeBlockBorder: (text: string) => string;
+    quote: (text: string) => string;
+    quoteBorder: (text: string) => string;
+    hr: (text: string) => string;
+    listBullet: (text: string) => string;
+    bold: (text: string) => string;
+    italic: (text: string) => string;
+    strikethrough: (text: string) => string;
+    underline: (text: string) => string;
+    highlightCode?: (code: string, lang?: string) => string[];
+    /**
+     * Resolve a mermaid ASCII rendering by fenced block source text.
+     * Return null to fall back to fenced code rendering.
+     */
+    resolveMermaidAscii?: (source: string) => string | null;
+    symbols: SymbolTheme;
+}
+export declare class Markdown implements Component {
+    #private;
+    constructor(text: string, paddingX: number, paddingY: number, theme: MarkdownTheme, defaultTextStyle?: DefaultTextStyle, codeBlockIndent?: number);
+    setText(text: string): void;
+    invalidate(): void;
+    render(width: number): string[];
+}
+/**
+ * Render inline markdown (bold, italic, code, links, strikethrough) to a styled string.
+ * Unlike the full Markdown component, this produces a single line with no block-level elements.
+ */
+export declare function renderInlineMarkdown(text: string, mdTheme: MarkdownTheme, baseColor?: (t: string) => string): string;

package/dist/types/components/select-list.d.ts

@@ -0,0 +1,46 @@
+import type { SymbolTheme } from "../symbols";
+import type { Component } from "../tui";
+export interface SelectItem {
+    value: string;
+    label: string;
+    description?: string;
+    /** Dim hint text shown inline after cursor when this item is selected */
+    hint?: string;
+}
+export interface SelectListTheme {
+    selectedPrefix: (text: string) => string;
+    selectedText: (text: string) => string;
+    description: (text: string) => string;
+    scrollInfo: (text: string) => string;
+    noMatch: (text: string) => string;
+    symbols: SymbolTheme;
+}
+export interface SelectListTruncatePrimaryContext {
+    text: string;
+    maxWidth: number;
+    columnWidth: number;
+    item: SelectItem;
+    isSelected: boolean;
+}
+export interface SelectListLayoutOptions {
+    minPrimaryColumnWidth?: number;
+    maxPrimaryColumnWidth?: number;
+    truncatePrimary?: (context: SelectListTruncatePrimaryContext) => string;
+}
+export declare class SelectList implements Component {
+    #private;
+    private readonly items;
+    private readonly maxVisible;
+    private readonly theme;
+    private readonly layout;
+    onSelect?: (item: SelectItem) => void;
+    onCancel?: () => void;
+    onSelectionChange?: (item: SelectItem) => void;
+    constructor(items: ReadonlyArray<SelectItem>, maxVisible: number, theme: SelectListTheme, layout?: SelectListLayoutOptions);
+    setFilter(filter: string): void;
+    setSelectedIndex(index: number): void;
+    invalidate(): void;
+    render(width: number): string[];
+    handleInput(keyData: string): void;
+    getSelectedItem(): SelectItem | null;
+}

package/dist/types/components/settings-list.d.ts

@@ -0,0 +1,31 @@
+import type { Component } from "../tui";
+export interface SettingItem {
+    /** Unique identifier for this setting */
+    id: string;
+    /** Display label (left side) */
+    label: string;
+    /** Optional description shown when selected */
+    description?: string;
+    /** Current value to display (right side) */
+    currentValue: string;
+    /** If provided, Enter/Space cycles through these values */
+    values?: string[];
+    /** If provided, Enter opens this submenu. Receives current value and done callback. */
+    submenu?: (currentValue: string, done: (selectedValue?: string) => void) => Component;
+}
+export interface SettingsListTheme {
+    label: (text: string, selected: boolean) => string;
+    value: (text: string, selected: boolean) => string;
+    description: (text: string) => string;
+    cursor: string;
+    hint: (text: string) => string;
+}
+export declare class SettingsList implements Component {
+    #private;
+    constructor(items: SettingItem[], maxVisible: number, theme: SettingsListTheme, onChange: (id: string, newValue: string) => void, onCancel: () => void);
+    /** Update an item's currentValue */
+    updateValue(id: string, newValue: string): void;
+    invalidate(): void;
+    render(width: number): string[];
+    handleInput(data: string): void;
+}

package/dist/types/components/spacer.d.ts

@@ -0,0 +1,11 @@
+import type { Component } from "../tui";
+/**
+ * Spacer component that renders empty lines
+ */
+export declare class Spacer implements Component {
+    #private;
+    constructor(lines?: number);
+    setLines(lines: number): void;
+    invalidate(): void;
+    render(_width: number): string[];
+}

package/dist/types/components/tab-bar.d.ts

@@ -0,0 +1,56 @@
+import type { Component } from "../tui";
+/** Tab definition */
+export interface Tab {
+    /** Unique identifier for the tab */
+    id: string;
+    /** Display label shown in the tab bar */
+    label: string;
+}
+/** Theme for styling the tab bar */
+export interface TabBarTheme {
+    /** Style for the label prefix (e.g., "Settings:") */
+    label: (text: string) => string;
+    /** Style for the currently active tab */
+    activeTab: (text: string) => string;
+    /** Style for inactive tabs */
+    inactiveTab: (text: string) => string;
+    /** Style for the hint text (e.g., "(tab to cycle)") */
+    hint: (text: string) => string;
+}
+/**
+ * Horizontal tab bar component.
+ *
+ * @example
+ * ```ts
+ * const tabs = [
+ *   { id: "config", label: "Config" },
+ *   { id: "tools", label: "Tools" },
+ * ];
+ * const tabBar = new TabBar("Settings", tabs, theme);
+ * tabBar.onTabChange = (tab) => console.log(`Switched to ${tab.id}`);
+ * ```
+ */
+export declare class TabBar implements Component {
+    #private;
+    /** Callback fired when the active tab changes */
+    onTabChange?: (tab: Tab, index: number) => void;
+    constructor(label: string, tabs: Tab[], theme: TabBarTheme, initialIndex?: number);
+    /** Get the currently active tab */
+    getActiveTab(): Tab;
+    /** Get the index of the currently active tab */
+    getActiveIndex(): number;
+    /** Set the active tab by index (clamped to valid range) */
+    setActiveIndex(index: number): void;
+    /** Move to the next tab (wraps to first tab after last) */
+    nextTab(): void;
+    /** Move to the previous tab (wraps to last tab before first) */
+    prevTab(): void;
+    invalidate(): void;
+    /**
+     * Handle keyboard input for tab navigation.
+     * @returns true if the input was handled, false otherwise
+     */
+    handleInput(data: string): boolean;
+    /** Render the tab bar, wrapping to multiple lines if needed */
+    render(width: number): string[];
+}

package/dist/types/components/text.d.ts

@@ -0,0 +1,13 @@
+import type { Component } from "../tui";
+/**
+ * Text component - displays multi-line text with word wrapping
+ */
+export declare class Text implements Component {
+    #private;
+    constructor(text?: string, paddingX?: number, paddingY?: number, customBgFn?: (text: string) => string);
+    getText(): string;
+    setText(text: string): void;
+    setCustomBgFn(customBgFn?: (text: string) => string): void;
+    invalidate(): void;
+    render(width: number): string[];
+}

package/dist/types/components/truncated-text.d.ts

@@ -0,0 +1,10 @@
+import type { Component } from "../tui";
+/**
+ * Text component that truncates to fit viewport width
+ */
+export declare class TruncatedText implements Component {
+    #private;
+    constructor(text: string, paddingX?: number, paddingY?: number);
+    invalidate(): void;
+    render(width: number): string[];
+}

package/dist/types/editor-component.d.ts

@@ -0,0 +1,36 @@
+import type { AutocompleteProvider } from "./autocomplete";
+import type { Component } from "./tui";
+/**
+ * Interface for custom editor components.
+ *
+ * This allows extensions to provide their own editor implementation
+ * (e.g., vim mode, emacs mode, custom keybindings) while maintaining
+ * compatibility with the core application.
+ */
+export interface EditorComponent extends Component {
+    /** Get the current text content */
+    getText(): string;
+    /** Set the text content */
+    setText(text: string): void;
+    /** Handle raw terminal input (key presses, paste sequences, etc.) */
+    handleInput(data: string): void;
+    /** Called when user submits (e.g., Enter key) */
+    onSubmit?: (text: string) => void;
+    /** Called when text changes */
+    onChange?: (text: string) => void;
+    /** Add text to history for up/down navigation */
+    addToHistory?(text: string): void;
+    /** Insert text at current cursor position */
+    insertTextAtCursor?(text: string): void;
+    /**
+     * Get text with any markers expanded (e.g., paste markers).
+     * Falls back to getText() if not implemented.
+     */
+    getExpandedText?(): string;
+    /** Set the autocomplete provider */
+    setAutocompleteProvider?(provider: AutocompleteProvider): void;
+    /** Border color function */
+    borderColor?: (str: string) => string;
+    /** Set horizontal padding */
+    setPaddingX?(padding: number): void;
+}

package/dist/types/fuzzy.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Fuzzy matching utilities.
+ * Matches if all query characters appear in order (not necessarily consecutive).
+ * Lower score = better match.
+ */
+export interface FuzzyMatch {
+    matches: boolean;
+    score: number;
+}
+export declare function fuzzyMatch(query: string, text: string): FuzzyMatch;
+/**
+ * Filter and sort items by fuzzy match quality (best matches first).
+ * Supports space-separated tokens: all tokens must match.
+ */
+export declare function fuzzyFilter<T>(items: T[], query: string, getText: (item: T) => string): T[];

package/dist/types/index.d.ts

@@ -0,0 +1,25 @@
+export * from "./autocomplete";
+export * from "./components/box";
+export * from "./components/cancellable-loader";
+export * from "./components/editor";
+export * from "./components/image";
+export * from "./components/input";
+export * from "./components/loader";
+export * from "./components/markdown";
+export * from "./components/select-list";
+export * from "./components/settings-list";
+export * from "./components/spacer";
+export * from "./components/tab-bar";
+export * from "./components/text";
+export * from "./components/truncated-text";
+export type * from "./editor-component";
+export * from "./fuzzy";
+export * from "./keybindings";
+export * from "./keys";
+export * from "./stdin-buffer";
+export type * from "./symbols";
+export * from "./terminal";
+export * from "./terminal-capabilities";
+export * from "./ttyid";
+export * from "./tui";
+export * from "./utils";