tessl/npm-terminal-kit

Comprehensive Node.js terminal library with 256 colors, interactive components, and advanced graphics capabilities

—

Pending

Overview

Eval results

Files

Document Model

Name: tessl/npm-terminal-kit
Author: tessl

The Document Model provides a high-level declarative UI framework for building complex terminal applications with components, layouts, and event handling. It offers a DOM-like structure for terminal interfaces.

Core Architecture

Base Classes

const Element: typeof import('./document/Element');
const Container: typeof import('./document/Container');
const Document: typeof import('./document/Document');

The document model is built on three foundational classes:

Element: Base class for all UI components
Container: Elements that can contain child elements
Document: Root container managing the entire UI

Document Creation

new Document(options: DocumentOptions): Document;

Create a new document instance to manage your UI.

interface DocumentOptions {
  outputDst?: Terminal;
  eventSource?: Terminal;
  x?: number;
  y?: number;
  width?: number;
  height?: number;
}

const term = require('terminal-kit').terminal;
const termkit = require('terminal-kit');

const document = new termkit.Document({
  outputDst: term,
  eventSource: term
});

// Enable event handling
term.grabInput({ mouse: 'button' });

Text Components

Static Text

new termkit.Text(options: TextOptions): Text;

Display static text content.

interface TextOptions {
  parent?: Container;
  content?: string;
  markup?: boolean;
  x?: number;
  y?: number;
  width?: number;
  height?: number;
  style?: object;
}

const text = new termkit.Text({
  parent: document,
  content: 'Hello, World!',
  x: 2,
  y: 2,
  style: { color: 'brightCyan' }
});

Animated Text

new termkit.AnimatedText(options: AnimatedTextOptions): AnimatedText;

Text with animation effects.

interface AnimatedTextOptions extends TextOptions {
  animation?: string;
  animationDelay?: number;
}

const animatedText = new termkit.AnimatedText({
  parent: document,
  content: 'Loading...',
  x: 5,
  y: 5,
  animation: 'typewriter'
});

Text Display and Input

Text Box

new termkit.TextBox(options: TextBoxOptions): TextBox;

Multi-line text display with scrolling support.

interface TextBoxOptions {
  parent?: Container;
  content?: string;
  markup?: boolean;
  x?: number;
  y?: number;
  width?: number;
  height?: number;
  wrap?: boolean;
  scrollable?: boolean;
  vScrollBar?: boolean;
  hScrollBar?: boolean;
  style?: object;
  scrollBarStyle?: object;
}

const textBox = new termkit.TextBox({
  parent: document,
  content: 'This is a multi-line text box.\nIt supports scrolling and wrapping.',
  x: 2,
  y: 4,
  width: 40,
  height: 8,
  scrollable: true,
  vScrollBar: true
});

Editable Text Box

new termkit.EditableTextBox(options: EditableTextBoxOptions): EditableTextBox;

Multi-line editable text area.

interface EditableTextBoxOptions extends TextBoxOptions {
  keyBindings?: object;
  readOnly?: boolean;
}

const editableTextBox = new termkit.EditableTextBox({
  parent: document,
  content: 'Edit this text...',
  x: 2,
  y: 2,
  width: 50,
  height: 10,
  scrollable: true
});

editableTextBox.on('submit', (content) => {
  term.green('Text submitted: %s\n', content);
});

Interactive Components

Button

new termkit.Button(options: ButtonOptions): Button;

Clickable button component.

interface ButtonOptions {
  parent?: Container;
  content?: string;
  value?: any;
  x?: number;
  y?: number;
  width?: number;
  height?: number;
  style?: object;
  focusStyle?: object;
  disabledStyle?: object;
  keyBindings?: object;
}

const button = new termkit.Button({
  parent: document,
  content: 'Click Me',
  x: 10,
  y: 5,
  width: 15,
  height: 3
});

button.on('submit', () => {
  term.green('Button clicked!\n');
});

Toggle Button

new termkit.ToggleButton(options: ToggleButtonOptions): ToggleButton;

Button that toggles between states.

interface ToggleButtonOptions extends ButtonOptions {
  turnedOnContent?: string;
  turnedOffContent?: string;
  turnedOn?: boolean;
  turnedOnStyle?: object;
  turnedOffStyle?: object;
}

const toggleButton = new termkit.ToggleButton({
  parent: document,
  turnedOffContent: 'OFF',
  turnedOnContent: 'ON',
  x: 5,
  y: 8,
  width: 10,
  turnedOn: false
});

toggleButton.on('toggle', (state) => {
  term('Toggle state: %s\n', state ? 'ON' : 'OFF');
});

Slider

new termkit.Slider(options: SliderOptions): Slider;

Horizontal slider control.

interface SliderOptions {
  parent?: Container;
  x?: number;
  y?: number;
  width?: number;
  min?: number;
  max?: number;
  value?: number;
  step?: number;
  style?: object;
  barStyle?: object;
  buttonStyle?: object;
  keyBindings?: object;
}

const slider = new termkit.Slider({
  parent: document,
  x: 5,
  y: 10,
  width: 30,
  min: 0,
  max: 100,
  value: 50,
  step: 5
});

slider.on('slide', (value) => {
  term.moveTo(1, 15)('Slider value: %d', value);
});

Input Components

Labeled Input

new termkit.LabeledInput(options: LabeledInputOptions): LabeledInput;

Input field with an associated label.

interface LabeledInputOptions {
  parent?: Container;
  label?: string;
  x?: number;
  y?: number;
  width?: number;
  height?: number;
  labelStyle?: object;
  inputStyle?: object;
  keyBindings?: object;
}

const labeledInput = new termkit.LabeledInput({
  parent: document,
  label: 'Name: ',
  x: 5,
  y: 12,
  width: 30
});

labeledInput.on('submit', (value) => {
  term.green('Entered name: %s\n', value);
});

Inline Input

new termkit.InlineInput(options: InlineInputOptions): InlineInput;

Compact inline input field.

interface InlineInputOptions {
  parent?: Container;
  x?: number;
  y?: number;
  width?: number;
  placeholder?: string;
  default?: string;
  style?: object;
  focusStyle?: object;
}

Inline File Input

new termkit.InlineFileInput(options: InlineFileInputOptions): InlineFileInput;

File selection input with auto-completion.

interface InlineFileInputOptions extends InlineInputOptions {
  baseDir?: string;
  allowedExtensions?: string[];
}

Menu Components

Inline Menu

new termkit.InlineMenu(options: InlineMenuOptions): InlineMenu;

Horizontal inline menu.

interface InlineMenuOptions {
  parent?: Container;
  items?: MenuItem[];
  x?: number;
  y?: number;
  keyBindings?: object;
  style?: object;
  focusStyle?: object;
  selectedStyle?: object;
}

interface MenuItem {
  content: string;
  value?: any;
  disabled?: boolean;
}

Row Menu

new termkit.RowMenu(options: RowMenuOptions): RowMenu;

Horizontal row-based menu.

interface RowMenuOptions {
  parent?: Container;
  items?: MenuItem[];
  x?: number;
  y?: number;
  width?: number;
  keyBindings?: object;
  style?: object;
  focusStyle?: object;
  selectedStyle?: object;
}

Column Menu

new termkit.ColumnMenu(options: ColumnMenuOptions): ColumnMenu;

Vertical column menu.

interface ColumnMenuOptions {
  parent?: Container;
  items?: MenuItem[];
  x?: number;
  y?: number;
  width?: number;
  height?: number;
  keyBindings?: object;
  style?: object;
  focusStyle?: object;
  selectedStyle?: object;
}

Column Menu Multi

new termkit.ColumnMenuMulti(options: ColumnMenuMultiOptions): ColumnMenuMulti;

Multi-select column menu.

interface ColumnMenuMultiOptions extends ColumnMenuOptions {
  multiSelect?: boolean;
  checkedContent?: string;
  uncheckedContent?: string;
}

Column Menu Mixed

new termkit.ColumnMenuMixed(options: ColumnMenuMixedOptions): ColumnMenuMixed;

Mixed-type column menu combining regular menu items with toggleable items.

interface ColumnMenuMixedOptions extends ColumnMenuOptions {
  // Items can be regular menu items or toggle items with states
  toggledStyle?: object;
  untoggledStyle?: object;
}

Select List

new termkit.SelectList(options: SelectListOptions): SelectList;

Scrollable selection list.

interface SelectListOptions {
  parent?: Container;
  items?: MenuItem[];
  x?: number;
  y?: number;
  width?: number;
  height?: number;
  scrollable?: boolean;
  master?: object;
  keyBindings?: object;
}

Select List Multi

new termkit.SelectListMulti(options: SelectListMultiOptions): SelectListMulti;

Multi-select scrollable selection list.

interface SelectListMultiOptions extends SelectListOptions {
  multiSelect?: boolean;
  checkedContent?: string;
  uncheckedContent?: string;
}

Drop Down Menu

new termkit.DropDownMenu(options: DropDownMenuOptions): DropDownMenu;

Expandable dropdown menu.

interface DropDownMenuOptions {
  parent?: Container;
  items?: MenuItem[];
  x?: number;
  y?: number;
  width?: number;
  button?: object;
  keyBindings?: object;
}

Layout and Structure

Layout Container

new termkit.Layout(options: LayoutOptions): Layout;

Container for organizing child elements.

interface LayoutOptions {
  parent?: Container;
  x?: number;
  y?: number;
  width?: number;
  height?: number;
  boxChars?: string;
  style?: object;
}

Border

new termkit.Border(options: BorderOptions): Border;

Decorative border around content.

interface BorderOptions {
  parent?: Container;
  x?: number;
  y?: number;
  width?: number;
  height?: number;
  boxChars?: string;
  style?: object;
}

Window

new termkit.Window(options: WindowOptions): Window;

Window container with title bar and borders.

interface WindowOptions {
  parent?: Container;
  title?: string;
  x?: number;
  y?: number;
  width?: number;
  height?: number;
  movable?: boolean;
  resizable?: boolean;
  style?: object;
  titleStyle?: object;
}

Advanced Components

Form

new termkit.Form(options: FormOptions): Form;

Container for form elements with validation.

interface FormOptions {
  parent?: Container;
  x?: number;
  y?: number;
  width?: number;
  height?: number;
  keyBindings?: object;
}

Text Table

new termkit.TextTable(options: TextTableOptions): TextTable;

Table display for structured data.

interface TextTableOptions {
  parent?: Container;
  x?: number;
  y?: number;
  width?: number;
  height?: number;
  columns?: TableColumn[];
  rows?: any[][];
  style?: object;
  headerStyle?: object;
  cellStyle?: object;
}

interface TableColumn {
  title: string;
  width?: number;
  align?: 'left' | 'center' | 'right';
}

Bar (Progress Bar)

new termkit.Bar(options: BarOptions): Bar;

Visual progress or status bar.

interface BarOptions {
  parent?: Container;
  x?: number;
  y?: number;
  width?: number;
  height?: number;
  value?: number;
  barChar?: string;
  style?: object;
  barStyle?: object;
}

Inspector

new termkit.Inspector(options: InspectorOptions): Inspector;

Object inspector for displaying complex data structures.

interface InspectorOptions {
  parent?: Container;
  x?: number;
  y?: number;
  width?: number;
  height?: number;
  object?: any;
  style?: object;
}

Usage Examples

Complete Application

const term = require('terminal-kit').terminal;
const termkit = require('terminal-kit');

// Create document
const document = new termkit.Document({
  outputDst: term,
  eventSource: term
});

// Enable input
term.grabInput({ mouse: 'button' });

// Create window
const window = new termkit.Window({
  parent: document,
  title: 'My Application',
  x: 2,
  y: 2,
  width: 60,
  height: 20,
  movable: true
});

// Add form elements
const nameInput = new termkit.LabeledInput({
  parent: window,
  label: 'Name: ',
  x: 2,
  y: 2,
  width: 30
});

const emailInput = new termkit.LabeledInput({
  parent: window,
  label: 'Email: ',
  x: 2,
  y: 4,
  width: 30
});

const submitButton = new termkit.Button({
  parent: window,
  content: 'Submit',
  x: 2,
  y: 6,
  width: 12,
  height: 3
});

// Handle events
submitButton.on('submit', () => {
  term.green('Form submitted!\n');
  term.green('Name: %s\n', nameInput.getValue());
  term.green('Email: %s\n', emailInput.getValue());
});

// Start the document
document.giveFocusTo(nameInput);

Dashboard Layout

const term = require('terminal-kit').terminal;
const termkit = require('terminal-kit');

const document = new termkit.Document({
  outputDst: term,
  eventSource: term
});

term.grabInput({ mouse: 'button' });

// Main layout
const mainLayout = new termkit.Layout({
  parent: document,
  x: 1,
  y: 1,
  width: term.width - 1,
  height: term.height - 1
});

// Status bar
const statusBar = new termkit.Bar({
  parent: mainLayout,
  x: 2,
  y: 2,
  width: 50,
  height: 1,
  value: 0.7,
  barChar: '█'
});

// Menu
const menu = new termkit.ColumnMenu({
  parent: mainLayout,
  items: [
    { content: 'Dashboard' },
    { content: 'Reports' },
    { content: 'Settings' },
    { content: 'Exit' }
  ],
  x: 2,
  y: 5,
  width: 20,
  height: 8
});

// Data table
const table = new termkit.TextTable({
  parent: mainLayout,
  x: 25,
  y: 5,
  width: 40,
  height: 10,
  columns: [
    { title: 'Name', width: 15 },
    { title: 'Status', width: 10 },
    { title: 'Value', width: 10, align: 'right' }
  ],
  rows: [
    ['Item 1', 'Active', '100'],
    ['Item 2', 'Inactive', '50'],
    ['Item 3', 'Pending', '75']
  ]
});

menu.on('submit', (buttonValue) => {
  term.moveTo(1, term.height)('Selected: %s', buttonValue.content);
});

Install with Tessl CLI

npx tessl i tessl/npm-terminal-kit

docs