> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/badlogic/pi-mono/llms.txt
> Use this file to discover all available pages before exploring further.

# TUI Types

> Type definitions for the TUI package

Core TypeScript types for the `@mariozechner/pi-tui` package.

## Import

```typescript theme={null}
import type {
  Component,
  Focusable,
  Terminal,
  OverlayOptions,
  EditorOptions,
  SelectItem,
} from "@mariozechner/pi-tui";
```

## Component Types

### Component

Base component interface.

```typescript theme={null}
interface Component {
  render(width: number): string[];
  handleInput?(data: string): void;
  wantsKeyRelease?: boolean;
  invalidate(): void;
}
```

### Focusable

Interface for components that can receive focus.

```typescript theme={null}
interface Focusable {
  focused: boolean;
}
```

## Terminal Types

### Terminal

Terminal abstraction interface.

```typescript theme={null}
interface Terminal {
  write(data: string): void;
  getSize(): { rows: number; cols: number };
  setRawMode(enabled: boolean): void;
  onData(callback: (data: string) => void): void;
  onResize(callback: () => void): void;
  clear(): void;
}
```

## Layout Types

### OverlayOptions

Options for overlay positioning.

```typescript theme={null}
interface OverlayOptions {
  width?: SizeValue;
  minWidth?: number;
  maxHeight?: SizeValue;
  anchor?: OverlayAnchor;
  offsetX?: number;
  offsetY?: number;
  row?: SizeValue;
  col?: SizeValue;
  margin?: OverlayMargin | number;
  visible?: (termWidth: number, termHeight: number) => boolean;
}
```

### SizeValue

```typescript theme={null}
type SizeValue = number | `${number}%`;
```

### OverlayAnchor

```typescript theme={null}
type OverlayAnchor =
  | "center"
  | "top-left"
  | "top-right"
  | "bottom-left"
  | "bottom-right"
  | "top-center"
  | "bottom-center"
  | "left-center"
  | "right-center";
```

### OverlayMargin

```typescript theme={null}
interface OverlayMargin {
  top?: number;
  right?: number;
  bottom?: number;
  left?: number;
}
```

### OverlayHandle

Opaque handle for overlay management.

```typescript theme={null}
type OverlayHandle = { readonly __brand: unique symbol };
```

## Editor Types

### EditorOptions

```typescript theme={null}
interface EditorOptions {
  placeholder?: string;
  language?: string;
  theme?: EditorTheme;
  keybindings?: EditorKeybindingsConfig;
  autocomplete?: AutocompleteProvider;
}
```

### EditorTheme

```typescript theme={null}
interface EditorTheme {
  text: string;
  cursor: string;
  selection: string;
  lineNumber: string;
  placeholder: string;
}
```

### EditorKeybindingsConfig

```typescript theme={null}
type EditorKeybindingsConfig = Record<string, EditorAction>;

type EditorAction =
  | "move-left"
  | "move-right"
  | "move-up"
  | "move-down"
  | "move-word-left"
  | "move-word-right"
  | "move-line-start"
  | "move-line-end"
  | "move-doc-start"
  | "move-doc-end"
  | "delete-char"
  | "delete-word"
  | "delete-line"
  | "newline"
  | "submit"
  | "cancel"
  | "undo"
  | "redo";
```

## List Types

### SelectItem

```typescript theme={null}
interface SelectItem {
  id: string;
  label: string;
  description?: string;
  disabled?: boolean;
}
```

### SelectListTheme

```typescript theme={null}
interface SelectListTheme {
  selected: string;
  unselected: string;
  disabled: string;
  searchQuery: string;
}
```

### SettingItem

```typescript theme={null}
interface SettingItem {
  id: string;
  label: string;
  value: string;
  description?: string;
}
```

### SettingsListTheme

```typescript theme={null}
interface SettingsListTheme {
  selected: string;
  unselected: string;
  value: string;
  description: string;
}
```

## Markdown Types

### MarkdownTheme

```typescript theme={null}
interface MarkdownTheme {
  heading1: string;
  heading2: string;
  heading3: string;
  bold: string;
  italic: string;
  code: string;
  codeBlock: string;
  link: string;
  list: string;
}
```

### DefaultTextStyle

```typescript theme={null}
interface DefaultTextStyle {
  color?: string;
  backgroundColor?: string;
  bold?: boolean;
  dim?: boolean;
  italic?: boolean;
}
```

## Image Types

### ImageOptions

```typescript theme={null}
interface ImageOptions {
  data: string;        // base64
  mimeType: string;
  maxWidth?: number;
  maxHeight?: number;
  theme?: ImageTheme;
}
```

### ImageTheme

```typescript theme={null}
interface ImageTheme {
  border?: string;
}
```

### ImageProtocol

```typescript theme={null}
type ImageProtocol = "kitty" | "iterm2" | null;
```

### TerminalCapabilities

```typescript theme={null}
interface TerminalCapabilities {
  imageProtocol: ImageProtocol;
  colorDepth: 24 | 256 | 16;
  cellDimensions: CellDimensions | null;
}
```

### CellDimensions

```typescript theme={null}
interface CellDimensions {
  width: number;   // pixels
  height: number;  // pixels
}
```

## Keyboard Types

### Key

Keyboard input representation.

```typescript theme={null}
interface Key {
  type: KeyEventType;
  sequence: string;
  name?: string;
  ctrl?: boolean;
  shift?: boolean;
  alt?: boolean;
  meta?: boolean;
}
```

### KeyEventType

```typescript theme={null}
type KeyEventType = "press" | "release" | "repeat";
```

### KeyId

```typescript theme={null}
type KeyId = string; // e.g., "ctrl+c", "enter", "esc"
```

## Autocomplete Types

### AutocompleteProvider

```typescript theme={null}
interface AutocompleteProvider {
  getSuggestions(text: string, cursorPos: number): Promise<AutocompleteItem[]>;
}
```

### AutocompleteItem

```typescript theme={null}
interface AutocompleteItem {
  text: string;
  label?: string;
  description?: string;
}
```

### SlashCommand

```typescript theme={null}
interface SlashCommand {
  name: string;
  description?: string;
  shortcut?: string;
}
```

## Fuzzy Matching Types

### FuzzyMatch

```typescript theme={null}
interface FuzzyMatch {
  item: string;
  score: number;
  indices: number[];
}
```

## Stdin Buffer Types

### StdinBufferOptions

```typescript theme={null}
interface StdinBufferOptions {
  batchSize?: number;
  batchDelayMs?: number;
}
```

### StdinBufferEventMap

```typescript theme={null}
interface StdinBufferEventMap {
  data: { data: string };
  error: { error: Error };
}
```

## Example: Type-Safe Component

```typescript theme={null}
import type {
  Component,
  Focusable,
  EditorOptions,
  SelectItem,
} from "@mariozechner/pi-tui";
import { Editor, SelectList } from "@mariozechner/pi-tui";

// Type-safe editor options
const editorOptions: EditorOptions = {
  placeholder: "Type here...",
  language: "typescript",
  keybindings: {
    "ctrl+enter": "submit",
    "escape": "cancel",
  },
};

const editor = new Editor(editorOptions);

// Type-safe select list
const items: SelectItem[] = [
  { id: "1", label: "Option 1" },
  { id: "2", label: "Option 2", disabled: true },
];

const list = new SelectList({ items });

// Type guard
if (isFocusable(editor)) {
  editor.focused = true;
}

function isFocusable(component: Component): component is Component & Focusable {
  return "focused" in component;
}
```