repository·master·Indexed 25 days ago
https://github.com/cronvel/terminal-kitA full-featured Node.js library for creating interactive terminal applications. It provides low-level color and style control (supporting 256 and 24-bit colors), mouse handling, and high-level UI components such as menus, progress bars, and input fields. It features a Document Model for complex interfaces with overlapping widgets and event dispatching, as well as an Inline Mode for traditional sequential output. The library includes advanced screen buffering with 32-bit composition and image loading and does not depend on ncurses.
ncurses.Terminal instance provides high-level methods to build feature-rich terminal applications. You can use these methods to handle keyboard inputs, manage the terminal color palette, create menus, capture text input (similar to readline), display progress bars, or implement special visual effects.Terminal Kit offers two distinct ways to build interfaces:
Document Model: Uses a portion or the entirety of the terminal area as a 'document' (similar to a webpage). Multiple widgets are present at specific screen locations and are all active simultaneously. This model supports overlapping widgets (like DropDownMenu), independent redraw conditions, keyboard focus management, event dispatching, widget cycling, and full mouse support. It is backed by ScreenBuffer.
Inline Mode: The traditional Terminal Kit approach where widgets are instantiated one at a time, line after line.
Note: Some widgets exist in both modes but may have different feature sets during the transition period where Document Model widgets are being made compatible with Inline Mode.
A TextBuffer is a specialized buffer designed for holding text content, making it suitable for implementing text areas or text editors. It is more flexible than a raw screenBuffer for text-centric tasks.
Every TextBuffer is backed by a screenBuffer (its dst or destination). Internally, it manages three distinct buffers:
The Container class is the base class for all document model objects that possess their own screenBuffer (such as a Document instance).
A container provides an inputDst (input destination) which serves as the outputDst (output destination) for all its children. This creates a drawing area for children. By using a rectangular viewport for clipping, the inputDst can be larger than the actual terminal display, allowing for features like virtual enlargement, scrolling, and overflow management.
A ScreenBuffer is a rectangular area containing cell data. Each cell in the buffer consists of:
bold, dim, italic, underline, blink, inverse, hidden, strike)There are two types of ScreenBuffer based on their write-destination:
ScreenBuffer (layering).Best Practice: For complex UIs with many moving elements, create one large ScreenBuffer that maps the entire terminal, then create smaller ScreenBuffer instances for specific UI components (widgets, sprites, or moving areas) that write into the main terminal buffer.
ScreenBuffer directly to the terminal, you can optimize performance by using the delta option in the .draw() method. This prevents the CPU-intensive task of refreshing the entire screen by only writing cells that have changed. The ScreenBuffer will automatically minimize the number of terminal escape sequences required to produce the new frame.Inspector utility allows you to interactively inspect JavaScript objects within the terminal. It provides a way to explore object properties and structures through a terminal-based interface.Terminal-kit supports text styling via markup sequences starting with a caret ^. Regular markup uses a single character following the caret to apply colors or text attributes. These sequences can be inserted directly into text content passed to most Terminal-kit functions.
^-: Dim^+: Bold^_: Underline^/: Italic^!: Inverse^k: Black^r: Red^g: Green^y: Yellow/Brown^b: Blue^m: Magenta^c: Cyan^w: White^K: Gray^R: Bright Red^G: Bright Green^Y: Bright Yellow^B: Bright Blue^M: Bright Magenta^C: Bright Cyan^W: Bright White^^: Output a literal caret ^^:: Reset style (default color/background/attributes)^ : Reset style and output a space^;: Special style reset (also resets attributes forced by a document-model's widget)^#: Shift mode (the next markup sequence will apply to the background instead of the foreground)"This is ^Ggreen^ and this is ^Rred^ !"term.processExit() to exit the application. This ensures that escape characters are cleaned up and the terminal's default style is restored, preventing visual artifacts in the user's shell.The Terminal instance provides low-level methods for controlling colors, styles, and cursor positioning. These methods are chainable and support three primary usage patterns:
term.red(true): Turns on red for all following output.term.red(false): Disables red and returns to default.term.red('Hello') is equivalent to term.red(true); term('Hello'); term.red(false);.Note: Some methods like term.reset() perform an action and cannot be toggled off.
To use the library, you can require the main package and access the .terminal property. This instance (term) is an instanceof termkit.Terminal and is configured to match your current terminal environment.
By convention in this documentation:
termkit refers to require('terminal-kit')term refers to termkit.terminal