TUI Types

Type definitions for the TUI package

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

Import

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

Component Types

Component

Base component interface.

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

Focusable

Interface for components that can receive focus.

interface Focusable {
  focused: boolean;
}

Terminal Types

Terminal

Terminal abstraction interface.

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.

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

type SizeValue = number | `${number}%`;

OverlayAnchor

type OverlayAnchor =
  | "center"
  | "top-left"
  | "top-right"
  | "bottom-left"
  | "bottom-right"
  | "top-center"
  | "bottom-center"
  | "left-center"
  | "right-center";

OverlayMargin

interface OverlayMargin {
  top?: number;
  right?: number;
  bottom?: number;
  left?: number;
}

OverlayHandle

Opaque handle for overlay management.

type OverlayHandle = { readonly __brand: unique symbol };

Editor Types

EditorOptions

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

EditorTheme

interface EditorTheme {
  text: string;
  cursor: string;
  selection: string;
  lineNumber: string;
  placeholder: string;
}

EditorKeybindingsConfig

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

interface SelectItem {
  id: string;
  label: string;
  description?: string;
  disabled?: boolean;
}

SelectListTheme

interface SelectListTheme {
  selected: string;
  unselected: string;
  disabled: string;
  searchQuery: string;
}

SettingItem

interface SettingItem {
  id: string;
  label: string;
  value: string;
  description?: string;
}

SettingsListTheme

interface SettingsListTheme {
  selected: string;
  unselected: string;
  value: string;
  description: string;
}

Markdown Types

MarkdownTheme

interface MarkdownTheme {
  heading1: string;
  heading2: string;
  heading3: string;
  bold: string;
  italic: string;
  code: string;
  codeBlock: string;
  link: string;
  list: string;
}

DefaultTextStyle

interface DefaultTextStyle {
  color?: string;
  backgroundColor?: string;
  bold?: boolean;
  dim?: boolean;
  italic?: boolean;
}

Image Types

ImageOptions

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

ImageTheme

interface ImageTheme {
  border?: string;
}

ImageProtocol

type ImageProtocol = "kitty" | "iterm2" | null;

TerminalCapabilities

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

CellDimensions

interface CellDimensions {
  width: number;   // pixels
  height: number;  // pixels
}

Keyboard Types

Key

Keyboard input representation.

interface Key {
  type: KeyEventType;
  sequence: string;
  name?: string;
  ctrl?: boolean;
  shift?: boolean;
  alt?: boolean;
  meta?: boolean;
}

KeyEventType

type KeyEventType = "press" | "release" | "repeat";

KeyId

type KeyId = string; // e.g., "ctrl+c", "enter", "esc"

Autocomplete Types

AutocompleteProvider

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

AutocompleteItem

interface AutocompleteItem {
  text: string;
  label?: string;
  description?: string;
}

SlashCommand

interface SlashCommand {
  name: string;
  description?: string;
  shortcut?: string;
}

Fuzzy Matching Types

FuzzyMatch

interface FuzzyMatch {
  item: string;
  score: number;
  indices: number[];
}

Stdin Buffer Types

StdinBufferOptions

interface StdinBufferOptions {
  batchSize?: number;
  batchDelayMs?: number;
}

StdinBufferEventMap

interface StdinBufferEventMap {
  data: { data: string };
  error: { error: Error };
}

Example: Type-Safe Component

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