### Screen Usage Examples

Source: https://unblessed.dev/docs/api/generated/widgets.screen.Class.Screen

Illustrates common use cases for the Screen class, including basic setup and event handling.

```APIDOC
## Examples

### Basic Initialization and Widget Addition
```javascript
import { Screen, Box } from "@unblessed/node";  
  
const screen = new Screen({
  smartCSR: true,
  title: "My App",
});
  
const box = new Box({
  parent: screen,
  top: "center",
  left: "center",
  width: "50%",
  height: "50%",
  content: "Hello World!",
  border: { type: "line" },
});
  
screen.key(["q", "C-c"], () => {
  screen.destroy();
  process.exit(0);
});
  
screen.render();
```

### Event Handling and Mouse Interaction
```javascript
const screen = new Screen({
  smartCSR: true,
  sendFocus: true,
});
  
const box = new Box({
  parent: screen,
  mouse: true,
  // ...
});
  
box.on("click", () => {
  box.setContent("Clicked!");
  screen.render();
});
  
screen.render();
```
```

--------------------------------

### Create Minimal Reproduction Example

Source: https://unblessed.dev/docs/advanced/troubleshooting

A minimal example to reproduce an issue, including necessary imports and setup. Useful for reporting bugs.

```javascript
// Minimal example that reproduces the issue
import { Screen, Box } from "@unblessed/node";

const screen = new Screen({ debug: true, dump: true });

const box = new Box({
  parent: screen,
  top: "center",
  left: "center",
  width: 50,
  height: 10,
  content: "Test",
  border: { type: "line" },
});

screen.render();

// Expected: Box appears centered
// Actual: Box appears in wrong position

console.log("Screenshot:", screen.screenshot());
console.log("Coordinates:", box.lpos);
```

--------------------------------

### Install @unblessed/browser and xterm

Source: https://unblessed.dev/docs/platforms/browser

Install the necessary packages using npm, pnpm, or yarn.

```bash
npm install @unblessed/browser xterm  
# or  
pnpm add @unblessed/browser xterm  
# or  
yarn add @unblessed/browser xterm  

```

--------------------------------

### Install @unblessed/node

Source: https://unblessed.dev/docs/platforms/nodejs

Install the Node.js package using npm, pnpm, or yarn.

```bash
npm install @unblessed/node  
# or  
pnpm add @unblessed/node  
# or  
yarn add @unblessed/node  


```

--------------------------------

### Box Widget Example

Source: https://unblessed.dev/docs/api/generated/widgets.box.Class.Box

Example demonstrating how to create and configure a Box widget with content and borders.

```javascript
import { Screen, Box } from "@unblessed/node";

const screen = new Screen();

const box = new Box({
  parent: screen,
  top: "center",
  left: "center",
  width: "50%",
  height: "50%",
  content: "Hello World!",
  border: {
    type: "line",
  },
  style: {
    fg: "white",
    bg: "blue",
    border: {
      fg: "#f0f0f0",
    },
  },
});

screen.render();
```

--------------------------------

### Install @unblessed/node for Modern API

Source: https://unblessed.dev/docs/getting-started/migration-from-blessed

Install the @unblessed/node package to begin upgrading to the modern API.

```bash
npm install @unblessed/node@alpha  
```

--------------------------------

### Install @unblessed/blessed

Source: https://unblessed.dev/docs/getting-started/migration-from-blessed

Install the @unblessed/blessed package using npm, pnpm, or yarn.

```bash
npm install @unblessed/blessed@alpha  
# or  
pnpm add @unblessed/blessed@alpha  
# or  
yarn add @unblessed/blessed@alpha  
```

--------------------------------

### Box Content Update Example

Source: https://unblessed.dev/docs/api/generated/widgets.box.Class.Box

Example showing how to update the content of an existing Box widget.

```javascript
const box = new Box({
  parent: screen,
  content: "Loading...",
});

// Update content later
box.setContent("Data loaded!");
screen.render();
```

--------------------------------

### Universal @unblessed Code Example

Source: https://unblessed.dev/docs/platforms/differences

This example demonstrates writing code that works in both Node.js and Browser environments with minimal platform-specific adjustments.

```javascript
// Works in both Node.js and Browser!  
import { Screen, Box, List } from "@unblessed/node"; // or browser  

const screen = new Screen(/* platform-specific options */);

const box = new Box({
  parent: screen,
  top: "center",
  left: "center",
  width: "50%",
  height: "50%",
  content: "Hello World!",
  border: { type: "line" },
});

screen.key("q", () => {
  /* platform-specific cleanup */
});

screen.render();

```

--------------------------------

### Verify unblessed Installation

Source: https://unblessed.dev/docs/getting-started/installation

Create and run this test file to confirm that unblessed is installed correctly and functional.

```typescript
// test.ts  
import { Screen, Box } from "@unblessed/node";  
  
const screen = new Screen();  
const box = new Box({
  parent: screen,
  content: "It works!",
  width: "50%",
  height: "50%",
  top: "center",
  left: "center",
  border: { type: "line" },
});  
  
screen.render();  
setTimeout(() => process.exit(0), 2000);  
```

--------------------------------

### Install @unblessed/vrt Package

Source: https://unblessed.dev/docs/advanced/testing

Install the VRT package as a dev dependency using npm, pnpm, or yarn.

```bash
npm install --save-dev @unblessed/vrt@alpha  
# or  
pnpm add -D @unblessed/vrt@alpha  
# or  
yarn add -D @unblessed/vrt@alpha  
```

--------------------------------

### setupTput()

Source: https://unblessed.dev/docs/api/generated/lib.program.Class.Program

Initializes the terminfo database and creates the tput object for terminal capability queries.

```APIDOC
## setupTput()

### Description
Set up the terminfo database. Creates the tput object for terminal capability queries.

### Returns
`void`
```

--------------------------------

### listen()

Source: https://unblessed.dev/docs/api/generated/lib.program.Class.Program

Initializes the program by setting up input and output listeners.

```APIDOC
## listen()

### Description
Initialize the program. Sets up input and output listeners.

### Returns
`void`
```

--------------------------------

### _getBottom(get?)

Source: https://unblessed.dev/docs/api/generated/widgets.filemanager.Class.FileManager

Internal method to get the bottom position of the element.

```APIDOC
## _getBottom(get?)

### Description

### Parameters
#### get? (boolean) - Optional

### Returns
number
```

--------------------------------

### setupDump()

Source: https://unblessed.dev/docs/api/generated/lib.program.Class.Program

Initializes dump logging, capturing all input and output to the log file.

```APIDOC
## setupDump()

### Description
Set up dump logging. Dumps all input and output to the log file.

### Returns
`void`
```

--------------------------------

### Quick Start with @unblessed/node

Source: https://unblessed.dev/docs/platforms/nodejs

Initialize a screen, create a box widget, set a global key handler, and render the TUI application.

```javascript
import { Screen, Box } from "@unblessed/node";  
  
// Create screen  
const screen = new Screen({  
  smartCSR: true,  
  title: "My TUI App",  
});  
  
// Create widget  
const box = new Box({  
  parent: screen,  
  top: "center",  
  left: "center",  
  width: "50%",  
  height: "50%",  
  content: "Hello from Node.js!",  
  border: { type: "line" },  
  style: { border: { fg: "cyan" } },  
});  
  
// Global key handler  
screen.key(["q", "C-c"], () => process.exit(0));  
  
// Render  
screen.render();  


```

--------------------------------

### _getTop(get?)

Source: https://unblessed.dev/docs/api/generated/widgets.filemanager.Class.FileManager

Internal method to get the top position of the element.

```APIDOC
## _getTop(get?)

### Description

### Parameters
#### get? (boolean) - Optional

### Returns
number
```

--------------------------------

### Initialize unblessed Project

Source: https://unblessed.dev/docs/getting-started/quick-start

Set up a new project directory, initialize npm, and install necessary dependencies like @unblessed/node and tsx.

```bash
mkdir my-tui-app
cd my-tui-app
pnpm init
pnpm add @unblessed/node tsx

```

--------------------------------

### Get IBottom

Source: https://unblessed.dev/docs/api/generated/widgets.line.Class.Line

Gets the inset bottom position of the widget. Inherited from Box.

```APIDOC
## Get IBottom

### Description
Gets the inset bottom position of the widget.

### Get Signature
```
get ibottom(): number
```

### Returns
- **number** - The inset bottom position.
```

--------------------------------

### Flexible Positioning and Sizing Examples

Source: https://unblessed.dev/docs/concepts/widgets

Demonstrates various ways to position and size widgets using absolute values, percentages, keywords like 'center', and calculations.

```javascript
// Absolute
{ top: 0, left: 0, width: 50, height: 10 }

// Percentage
{ top: '10%', left: '20%', width: '50%', height: '80%' }

// Center
{ top: 'center', left: 'center', width: 30, height: 10 }

// Mixed
{ top: 2, left: 'center', width: '50%', height: 10 }

// Calculated
{ top: 0, left: 0, right: 0, bottom: 0 }  // Fill parent
{ width: '100%-10', height: '100%-5' }    // With margin
```

--------------------------------

### Get TPadding

Source: https://unblessed.dev/docs/api/generated/widgets.image.Class.Image

Gets the top padding of the widget. This property is inherited from the Box class.

```APIDOC
## TPadding

### Get Signature
```
get tpadding(): number
```

### Returns
- `number`
```

--------------------------------

### Basic HTML Setup for Terminal

Source: https://unblessed.dev/docs/platforms/browser

Set up the HTML structure to host the XTerm.js terminal.

```html
<!DOCTYPE html>  
<html>  
  <head>  
    <link rel="stylesheet" href="node_modules/xterm/css/xterm.css" />  
  </head>  
  <body>  
    <div id="terminal"></div>  
    <script type="module" src="./app.js"></script>  
  </body>  
</html>  

```

--------------------------------

### Get IHeight

Source: https://unblessed.dev/docs/api/generated/widgets.image.Class.Image

Gets the inset height of the widget. This property is inherited from the Box class.

```APIDOC
## IHeight

### Get Signature
```
get iheight(): number
```

### Returns
- `number`
```

--------------------------------

### Initialize Node.js Screen

Source: https://unblessed.dev/docs/platforms/differences

Automatic runtime initialization for Node.js. No specific options are required for basic setup.

```javascript
import { Screen, Box } from "@unblessed/node";  
  
// Runtime auto-initialized with Node.js APIs  
const screen = new Screen();  

```

--------------------------------

### Get IWidth

Source: https://unblessed.dev/docs/api/generated/widgets.image.Class.Image

Gets the inset width of the widget. This property is inherited from the Box class.

```APIDOC
## IWidth

### Get Signature
```
get iwidth(): number
```

### Returns
- `number`
```

--------------------------------

### Initialize Screen and Basic Widget

Source: https://unblessed.dev/docs/api/generated/widgets.screen.Class.Screen

Demonstrates initializing a Screen with a title and adding a Box widget. Includes basic key binding for quitting the application.

```typescript
import { Screen, Box } from "@unblessed/node";  
  
const screen = new Screen({
  smartCSR: true,
  title: "My App",
});

const box = new Box({
  parent: screen,
  top: "center",
  left: "center",
  width: "50%",
  height: "50%",
  content: "Hello World!",
  border: { type: "line" },
});

screen.key(["q", "C-c"], () => {
  screen.destroy();
  process.exit(0);
});

screen.render();

```

--------------------------------

### Get User Property with get

Source: https://unblessed.dev/docs/api/generated/widgets.prompt.Class.Prompt

Retrieves a user-defined property by name, with an optional default value.

```typescript
get(name, value?)
```

--------------------------------

### Constructor

Source: https://unblessed.dev/docs/api/generated/widgets.question.Class.Question

Initializes a new instance of the Question class.

```APIDOC
## Constructor

> **new Question**(`options`): `Question`

Defined in: packages/core/src/widgets/question.ts:30

### Parameters
#### options
`QuestionOptions` = `{}`

### Returns
`Question`

### Overrides
`Box`.`constructor`
```

--------------------------------

### Get IRight

Source: https://unblessed.dev/docs/api/generated/widgets.loading.Class.Loading

Gets the inset right position of the widget. This property is inherited from the Box class.

```APIDOC
## Get IRight

### Description
Gets the inset right position of the widget.

### Get Signature
`get iright(): number`
```

--------------------------------

### enter()

Source: https://unblessed.dev/docs/api/generated/widgets.screen.Class.Screen

Enters the alternate screen buffer and initializes the screen. This is automatically called when the screen is created.

```APIDOC
## enter()

### Description
Enter the alternate screen buffer and initialize the screen. Automatically called when the screen is created.

### Method Signature
`enter(): void`

### Returns
- `void`
```

--------------------------------

### Get ITop

Source: https://unblessed.dev/docs/api/generated/widgets.loading.Class.Loading

Gets the inset top position of the widget. This property is inherited from the Box class.

```APIDOC
## Get ITop

### Description
Gets the inset top position of the widget.

### Get Signature
`get itop(): number`
```

--------------------------------

### Organize Test Fixtures Directory Structure

Source: https://unblessed.dev/docs/advanced/testing

Illustrates a recommended directory structure for organizing VRT recording fixtures to maintain a clean and manageable test suite.

```bash
__tests__/
├── fixtures/
│   ├── components/
│   │   ├── box-simple.vrt.json
│   │   ├── box-border.vrt.json
│   │   └── list-items.vrt.json
│   ├── layouts/
│   │   ├── dashboard.vrt.json
│   │   └── form.vrt.json
│   └── interactions/
│       ├── menu-navigation.vrt.json
│       └── form-submit.vrt.json
└── integration.test.ts

```

--------------------------------

### Get ILeft

Source: https://unblessed.dev/docs/api/generated/widgets.loading.Class.Loading

Gets the inset left position of the widget. This property is inherited from the Box class.

```APIDOC
## Get ILeft

### Description
Gets the inset left position of the widget.

### Get Signature
`get ileft(): number`
```

--------------------------------

### Get IBottom

Source: https://unblessed.dev/docs/api/generated/widgets.image.Class.Image

Gets the inset bottom coordinate of the widget. This property is inherited from the Box class.

```APIDOC
## IBottom

### Get Signature
```
get ibottom(): number
```

### Returns
- `number`
```

--------------------------------

### Log Widget Initialization

Source: https://unblessed.dev/docs/api/generated/widgets.log.Class.Log

Demonstrates how to create and initialize a Log widget with basic and advanced options.

```APIDOC
## Constructor

### new Log(options)

**Parameters**

*   `options` (LogOptions): Configuration options for the Log widget.

**Returns**

*   `Log`: An instance of the Log widget.

### Example 1: Basic Initialization

```javascript
const log = new Log({
  parent: screen,
  scrollback: 1000,
  border: { type: "line" },
});

log.log("Server started");
log.log("User %s connected", username);
```

### Example 2: With Static Header and Footer

```javascript
const log = new Log({
  parent: screen,
  scrollback: 1000,
  staticHeader: "=== Application Logs ===",
  staticFooter: "[↑/↓] Scroll | [Q] Quit",
});
```
```

--------------------------------

### Static Widget Example

Source: https://unblessed.dev/docs/api/generated/widgets.static.Class.Static

Demonstrates how to use the Static widget to display a list of completed tasks. New tasks are added and the widget updates to show them without re-rendering previous content.

```APIDOC
## Example
```
const completedTasks = [];  
const staticWidget = new Static({
  parent: screen,
  top: 0,
  left: 0,
  width: "100%",
  renderItem: (item, index) => `✓ Task ${index + 1}: ${item}`,
});

// Add new tasks - only new items render
completedTasks.push("Setup project");
staticWidget.setItems(completedTasks);
screen.render();

completedTasks.push("Write code");
staticWidget.setItems(completedTasks);
screen.render();
```
```

--------------------------------

### Get IRight

Source: https://unblessed.dev/docs/api/generated/widgets.image.Class.Image

Gets the inset right coordinate of the widget. This property is inherited from the Box class.

```APIDOC
## IRight

### Get Signature
```
get iright(): number
```

### Returns
- `number`
```

--------------------------------

### Create a Basic Terminal UI with unblessed

Source: https://unblessed.dev/docs/getting-started/introduction

This example demonstrates how to create a simple terminal UI with a box displaying 'Hello unblessed!'. It requires importing Screen and Box from '@unblessed/node'. The screen is initialized with smartCSR enabled, and a box is configured with specific positioning, dimensions, content, tags, border, and styling. The application exits when 'q' or 'C-c' is pressed.

```typescript
import { Screen, Box } from "@unblessed/node";  
  
const screen = new Screen({ smartCSR: true });  
  
const box = new Box({  
  parent: screen,  
  top: "center",  
  left: "center",  
  width: "50%",  
  height: "50%",  
  content: "Hello {bold}unblessed{/bold}!",  
  tags: true,  
  border: { type: "line" },  
  style: {  
    fg: "white",  
    border: { fg: "cyan" },  
  },  
});  
  
screen.key(["q", "C-c"], () => process.exit(0));  
screen.render();  


```

--------------------------------

### Get ITop

Source: https://unblessed.dev/docs/api/generated/widgets.image.Class.Image

Gets the inset top coordinate of the widget. This property is inherited from the Box class.

```APIDOC
## ITop

### Get Signature
```
get itop(): number
```

### Returns
- `number`
```

--------------------------------

### Get ILeft

Source: https://unblessed.dev/docs/api/generated/widgets.image.Class.Image

Gets the inset left coordinate of the widget. This property is inherited from the Box class.

```APIDOC
## ILeft

### Get Signature
```
get ileft(): number
```

### Returns
- `number`
```

--------------------------------

### Dialog Usage Example

Source: https://unblessed.dev/docs/api/generated/widgets.dialog.Class.Dialog

Demonstrates how to create, show, and hide a Dialog instance, including automatic ESC key handling.

```APIDOC
## Examples​

```
const dialog = new Dialog({
  parent: screen,
  width: "50%",
  height: "50%",
  content: "Dialog content",
  border: { type: "line" },
  label: " Dialog Title ",
});

dialog.show();
screen.render();

// ESC key automatically hides the dialog
// Or manually:
dialog.hide();
screen.render();
```
```

--------------------------------

### Padding Examples

Source: https://unblessed.dev/docs/concepts/widgets

Illustrates how to add space inside widget borders, either uniformly or on a per-side basis.

```javascript
// Uniform
{ padding: 1 }

// Per side
{ padding: { left: 2, right: 2, top: 1, bottom: 1 } }
```

--------------------------------

### Instantiate and Use Static Widget

Source: https://unblessed.dev/docs/api/generated/widgets.static.Class.Static

Demonstrates how to create a Static widget, add items, and re-render the screen. New items are added to the existing content without affecting previously rendered items.

```typescript
const completedTasks = [];  
const staticWidget = new Static({  
  parent: screen,  
  top: 0,  
  left: 0,  
  width: "100%",  
  renderItem: (item, index) => `✓ Task ${index + 1}: ${item}`,  
});  
  
// Add new tasks - only new items render  
completedTasks.push("Setup project");  
staticWidget.setItems(completedTasks);  
screen.render();  
  
completedTasks.push("Write code");  
staticWidget.setItems(completedTasks);  
screen.render();  


```

--------------------------------

### bootstrap()

Source: https://unblessed.dev/docs/api/generated/widgets.terminal.Class.Terminal

Initializes the terminal. This method should be called before any other terminal operations.

```APIDOC
## bootstrap()

### Description
Initializes the terminal.

### Method
`bootstrap`

### Returns
`void`
```

--------------------------------

### Widget Lifecycle Example

Source: https://unblessed.dev/docs/concepts/widgets

Illustrates the typical lifecycle of a widget from construction to destruction. Ensure proper cleanup by detaching and destroying widgets when no longer needed.

```javascript
const box = new Box({  
  /* options */  
}); // 1. Construction  
box.attach(parent); // 2. Attachment  
screen.render(); // 3. Rendering  
box.on("click", handler); // 4. Events  
box.setContent("new content"); // 5. Updates  
box.detach(); // 6. Detachment  
box.destroy(); // 7. Destruction  

```

--------------------------------

### Get and Set bottom Property

Source: https://unblessed.dev/docs/api/generated/widgets.radiobutton.Class.RadioButton

Gets or sets the bottom coordinate of the widget. This property is inherited from Checkbox.

```typescript
get bottom(): number
```

```typescript
set bottom(val: any): void
```

--------------------------------

### Get and Set top Property

Source: https://unblessed.dev/docs/api/generated/widgets.radiobutton.Class.RadioButton

Gets or sets the top coordinate of the widget. This property is inherited from Checkbox.

```typescript
get top(): number
```

```typescript
set top(val: any): void
```

--------------------------------

### Create and Render a Box Widget

Source: https://unblessed.dev/docs/api/generated/widgets.box.Class.Box

Demonstrates how to create a basic Box widget with content, borders, and styling, and then render it to the screen. Ensure you import Screen and Box from '@unblessed/node'.

```typescript
import { Screen, Box } from "@unblessed/node";  
  
const screen = new Screen();  
  
const box = new Box({
  parent: screen,
  top: "center",
  left: "center",
  width: "50%",
  height: "50%",
  content: "Hello World!",
  border: {
    type: "line",
  },
  style: {
    fg: "white",
    bg: "blue",
    border: {
      fg: "#f0f0f0",
    },
  },
});  
  
screen.render();  

```

--------------------------------

### Get and Set right Property

Source: https://unblessed.dev/docs/api/generated/widgets.radiobutton.Class.RadioButton

Gets or sets the right coordinate of the widget. This property is inherited from Checkbox.

```typescript
get right(): number
```

```typescript
set right(val: any): void
```

--------------------------------

### Get and Set left Property

Source: https://unblessed.dev/docs/api/generated/widgets.radiobutton.Class.RadioButton

Gets or sets the left coordinate of the widget. This property is inherited from Checkbox.

```typescript
get left(): number
```

```typescript
set left(val: any): void
```

--------------------------------

### Get Top Padding

Source: https://unblessed.dev/docs/api/generated/widgets.bigtext.Class.BigText

Gets the top padding value of the widget. This property is inherited from the Box class.

```APIDOC
## Top Padding (tpadding)

### Description
Gets the top padding value of the widget.

#### Get Signature
> **get** **tpadding**(): `number`

### Returns
`number`.
```

--------------------------------

### Platform-Agnostic Widget Example

Source: https://unblessed.dev/docs/platforms/differences

Create reusable UI components like StatusBar that work across different platforms by relying on abstract interfaces and common functionalities.

```typescript
export class StatusBar extends Box {
  constructor(options: BoxOptions) {
    super({
      ...options,
      height: 3,
      bottom: 0,
      left: 0,
      right: 0,
      style: { bg: "blue", fg: "white" },
    });
  }

  setStatus(message: string) {
    this.setContent(`  ${message}`);
    this.screen?.render();
  }
}

// Works in both platforms!
const status = new StatusBar({ parent: screen });
status.setStatus("Ready");

```

--------------------------------

### Get Inner Height

Source: https://unblessed.dev/docs/api/generated/widgets.bigtext.Class.BigText

Gets the inner height value of the widget. This property is inherited from the Box class.

```APIDOC
## Inner Height (iheight)

### Description
Gets the inner height value of the widget.

#### Get Signature
> **get** **iheight**(): `number`

### Returns
`number`.
```

--------------------------------

### Constructor

Source: https://unblessed.dev/docs/api/generated/widgets.terminal.Class.Terminal

Initializes a new instance of the Terminal class.

```APIDOC
## Constructor

### Description
Initializes a new instance of the Terminal class.

### Signature
```typescript
new Terminal(options?: TerminalOptions)
```

### Parameters
#### options
- **options** (`TerminalOptions`): Optional. Configuration options for the terminal. Defaults to `{}`.

### Returns
- `Terminal`: An instance of the Terminal class.
```

--------------------------------

### Get Inner Width

Source: https://unblessed.dev/docs/api/generated/widgets.bigtext.Class.BigText

Gets the inner width value of the widget. This property is inherited from the Box class.

```APIDOC
## Inner Width (iwidth)

### Description
Gets the inner width value of the widget.

#### Get Signature
> **get** **iwidth**(): `number`

### Returns
`number`.
```

--------------------------------

### Video Constructor

Source: https://unblessed.dev/docs/api/generated/widgets.video.Class.Video

Initializes a new instance of the Video class. It accepts an optional options object of type VideoOptions.

```APIDOC
## Constructor

### new Video(options)

**Parameters:**
* `options` (VideoOptions) - Optional. Defaults to `{}`.

**Returns:**
* `Video`
```

--------------------------------

### Get Inner Bottom

Source: https://unblessed.dev/docs/api/generated/widgets.bigtext.Class.BigText

Gets the inner bottom value of the widget. This property is inherited from the Box class.

```APIDOC
## Inner Bottom (ibottom)

### Description
Gets the inner bottom value of the widget.

#### Get Signature
> **get** **ibottom**(): `number`

### Returns
`number`.
```

--------------------------------

### Create an Interactive List

Source: https://unblessed.dev/docs/examples/getting-started/interactive-list

This snippet shows how to create a fully interactive list with keyboard and mouse support. It includes setup for the screen, list, and a status box, along with event handling for item selection and key bindings for quitting.

```javascript
import { Screen, List, Box } from "@unblessed/node";  
  
const screen = new Screen({ smartCSR: true });  
  
const list = new List({
  parent: screen,
  top: "center",
  left: "center",
  width: "50%",
  height: "50%",
  label: " {bold}{cyan-fg}Menu{/cyan-fg}{/bold} ",
  tags: true,
  keys: true, // Enable keyboard navigation
  vi: true, // Enable vi-style keys (j/k)
  mouse: true, // Enable mouse selection
  border: {
    type: "line",
  },
  style: {
    fg: "white",
    border: { fg: "cyan" },
    selected: {
      bg: "cyan",
      fg: "black",
    },
  },
  items: ["Option 1", "Option 2", "Option 3", "Option 4", "Option 5"],
});
  
const statusBox = new Box({
  parent: screen,
  top: 3,
  left: "center",
  width: "50%",
  height: 3,
  content: "Select an item with arrow keys or mouse",
  tags: true,
  style: {
    fg: "yellow",
  },
});
  
list.on("select", (item, index) => {
  statusBox.setContent(
    `{bold}Selected:{/bold} ${item.getText()} (index: ${index})`,
  );
  screen.render();
});
  
list.focus();
screen.key(["q", "C-c"], () => process.exit(0));
screen.render();

```

--------------------------------

### Get Inner Right

Source: https://unblessed.dev/docs/api/generated/widgets.bigtext.Class.BigText

Gets the inner right value of the widget. This property is inherited from the Box class.

```APIDOC
## Inner Right (iright)

### Description
Gets the inner right value of the widget.

#### Get Signature
> **get** **iright**(): `number`

### Returns
`number`.
```

--------------------------------

### Prompt Constructor

Source: https://unblessed.dev/docs/api/generated/widgets.prompt.Class.Prompt

Initializes a new instance of the Prompt class. It accepts an optional PromptOptions object.

```APIDOC
## Constructor

### new Prompt(options)

**Parameters:**
* **options** (`PromptOptions` = `{}`): An optional object to configure the prompt.

**Returns:**
* `Prompt`: An instance of the Prompt class.

**Overrides:**
* `Box.constructor`
```

--------------------------------

### Get Inner Top

Source: https://unblessed.dev/docs/api/generated/widgets.bigtext.Class.BigText

Gets the inner top value of the widget. This property is inherited from the Box class.

```APIDOC
## Inner Top (itop)

### Description
Gets the inner top value of the widget.

#### Get Signature
> **get** **itop**(): `number`

### Returns
`number`.
```

--------------------------------

### Initialize XTerm.js and @unblessed/browser Screen

Source: https://unblessed.dev/docs/platforms/browser

Initialize XTerm.js, load the fit addon, and create an unblessed screen with a Box widget.

```javascript
import { Terminal } from "xterm";  
import { FitAddon } from "@xterm/addon-fit";  
import { Screen, Box } from "@unblessed/browser";  
  
// Create XTerm terminal  
const term = new Terminal({
  cursorBlink: false,  
  fontSize: 14,  
  theme: {  
    background: "#1e1e1e",  
    foreground: "#d4d4d4",  
  },
});  
  
// Add fit addon  
const fitAddon = new FitAddon();  
term.loadAddon(fitAddon);  
  
// Open terminal in DOM  
term.open(document.getElementById("terminal"));  
fitAddon.fit();  
  
// Create unblessed screen with terminal  
const screen = new Screen({ terminal: term });  
  
// Create widgets  
const box = new Box({
  parent: screen,  
  top: "center",  
  left: "center",  
  width: "50%",  
  height: "50%",  
  content: "Hello from Browser!",  
  border: { type: "line" },  
  style: { border: { fg: "cyan" } },
});  
  
// Render  
screen.render();  

```

--------------------------------

### Get Inner Left

Source: https://unblessed.dev/docs/api/generated/widgets.bigtext.Class.BigText

Gets the inner left value of the widget. This property is inherited from the Box class.

```APIDOC
## Inner Left (ileft)

### Description
Gets the inner left value of the widget.

#### Get Signature
> **get** **ileft**(): `number`

### Returns
`number`.
```

--------------------------------

### Screen Constructor

Source: https://unblessed.dev/docs/api/generated/widgets.screen.Class.Screen

Initializes a new instance of the Screen class. Accepts ScreenOptions for configuration.

```APIDOC
## new Screen(options)

### Description
Initializes a new instance of the Screen class.

### Parameters
#### options
`ScreenOptions` = `{}` - Configuration options for the Screen.

### Returns
`Screen` - A new Screen instance.
```

--------------------------------

### Load Configuration Safely in Browser and Node.js

Source: https://unblessed.dev/docs/platforms/differences

Avoid direct file system access in the browser. Use `fetch` for browser environments and `readFileSync` for Node.js, checking for file system availability.

```javascript
// DON'T  
const config = readFileSync("./config.json"); // Fails in browser  
  
// DO  
async function loadConfig() {  
  if (hasFileSystem()) {  
    return readFileSync("./config.json", "utf8");  
  } else {  
    const response = await fetch("/config.json");  
    return response.text();  
  }  
}  
```

--------------------------------

### Install @unblessed/blessed for Blessed Compatibility

Source: https://unblessed.dev/docs/getting-started/installation

Install the compatibility layer for existing blessed applications. This package ensures 100% backward compatibility.

```bash
pnpm add @unblessed/blessed  
# or  
npm install @unblessed/blessed  
```

--------------------------------

### Install Node.js Package

Source: https://unblessed.dev/docs/platforms/differences

Use this command to add the Node.js specific package for @unblessed.

```bash
pnpm add @unblessed/node  

Includes:
  * Node.js runtime implementation
  * All core widgets
  * Direct TTY support

```

--------------------------------

### Recommended Widget Initialization

Source: https://unblessed.dev/docs/concepts/widgets

Use the 'parent' option during widget construction for recommended initialization. Avoid manually appending widgets after creation.

```javascript
// ✅ Recommended  
const box = new Box({ parent: screen });  

// ❌ Avoid  
const box = new Box();  
screen.append(box);  

```

--------------------------------

### Terminal Update Example

Source: https://unblessed.dev/docs/concepts/rendering

This example shows a typical diff output and how it's translated into terminal escape sequences for updating only changed cells.

```javascript
// Example diff output  
[  
  { x: 10, y: 5, text: 'Hello', attr: { fg: 'cyan' } },  
  { x: 10, y: 6, text: 'World', attr: { fg: 'cyan' } },  
]  
  
// Sent to terminal as escape sequences  
\x1b[5;10H\x1b[36mHello\x1b[0m  
\x1b[6;10H\x1b[36mWorld\x1b[0m  
```

--------------------------------

### _getShrink(xi, xl, yi, yl, get?)

Source: https://unblessed.dev/docs/api/generated/widgets.dialog.Class.Dialog

Calculates and returns shrink information based on provided coordinates and an optional get flag. Inherited from Box._getShrink.

```APIDOC
## _getShrink(xi, xl, yi, yl, get?)

### Description
Calculates and returns shrink information based on provided coordinates and an optional get flag.

### Parameters
#### xi
`number`
#### xl
`number`
#### yi
`number`
#### yl
`number`
#### get?
`boolean`

### Returns
`any`

### Inherited from
`Box`.`_getShrink`
```

--------------------------------

### Input Constructor

Source: https://unblessed.dev/docs/api/generated/widgets.input.Class.Input

Initializes a new instance of the Input widget. It accepts an optional options object.

```APIDOC
## Constructor

> **new Input**(`options`): `Input`

Defined in: packages/core/src/widgets/input.ts:20

### Parameters

#### options

`InputOptions` = `{}`

### Returns

`Input`

### Overrides

`Box`.`constructor`
```

--------------------------------

### iheight

Source: https://unblessed.dev/docs/api/generated/widgets.terminal.Class.Terminal

Gets the inner height of the widget.

```APIDOC
## iheight

### Description
Gets the inner height of the widget.

### Get Signature
> **get** **iheight**(): `number`
```

--------------------------------

### spawn()

Source: https://unblessed.dev/docs/api/generated/widgets.screen.Class.Screen

Spawns a new process in the foreground. The application will return to the blessed app after the spawned process exits.

```APIDOC
## spawn()

### Description
Spawn a process in the foreground, return to blessed app after exit. Temporarily leaves the alternate screen buffer and restores it after the process exits.

### Method
spawn

### Parameters
#### Path Parameters
- **file** (string) - Required - Command to execute
- **args?** (any) - Optional - Arguments to pass to the command
- **options?** (any) - Optional - Options to pass to child_process.spawn

### Returns
any - ChildProcess instance
```

--------------------------------

### iwidth

Source: https://unblessed.dev/docs/api/generated/widgets.terminal.Class.Terminal

Gets the inner width of the widget.

```APIDOC
## iwidth

### Description
Gets the inner width of the widget.

### Get Signature
> **get** **iwidth**(): `number`
```

--------------------------------

### _getHeight(get?)

Source: https://unblessed.dev/docs/api/generated/widgets.scrollabletext.Class.ScrollableText

Retrieves the height of the element.

```APIDOC
## _getHeight(get?)

### Description
Retrieves the height of the element.

### Method
`_getHeight(get?: boolean): number`

### Parameters
#### get
- **get** (boolean) - Optional parameter.

### Returns
`number`
```

--------------------------------

### postEnter()

Source: https://unblessed.dev/docs/api/generated/widgets.screen.Class.Screen

Performs post-enter initialization, including setting up debug logs and warnings if enabled. Automatically called after enter().

```APIDOC
## postEnter()

### Description
Perform post-enter initialization. Sets up debug log and warnings if enabled. Automatically called after enter().

### Method Signature
`postEnter(): void`

### Returns
- `void`
```

--------------------------------

### _listenKeys()

Source: https://unblessed.dev/docs/api/generated/widgets.screen.Class.Screen

Internal method to set up keypress event handling for the screen, optionally for a specific element. This is typically not called directly by users.

```APIDOC
## _listenKeys()

### Description
Internal method to set up keypress event handling for the screen and optionally an element.

### Method Signature
`_listenKeys(el?: any): void`

### Parameters
#### el
- **el** (any, optional) - Element to register as keyable.

### Returns
- `void`
```

--------------------------------

### _getWidth(get?)

Source: https://unblessed.dev/docs/api/generated/widgets.scrollabletext.Class.ScrollableText

Retrieves the width of the element.

```APIDOC
## _getWidth(get?)

### Description
Retrieves the width of the element.

### Method
`_getWidth(get?: boolean): number`

### Parameters
#### get
- **get** (boolean) - Optional parameter.

### Returns
`number`
```

--------------------------------

### right

Source: https://unblessed.dev/docs/api/generated/widgets.message.Class.Message

Get the right coordinate of the widget.

```APIDOC
## Get right

### Description
Retrieves the right coordinate of the widget.

### Method
GET

### Endpoint
widgets.message.Class.right

### Returns
`number` - The right coordinate.
```

--------------------------------

### Initialize Browser Screen with XTerm.js

Source: https://unblessed.dev/docs/platforms/differences

Requires an XTerm.js terminal instance to be created and opened before initializing the Screen. Pass the terminal instance via options.

```javascript
import { Terminal } from "xterm";  
import { Screen, Box } from "@unblessed/browser";  
  
// Create and mount terminal  
const term = new Terminal();  
term.open(document.getElementById("terminal"));  
  
// Runtime auto-initialized with polyfills  
const screen = new Screen({ terminal: term });  

```

--------------------------------

### iheight

Source: https://unblessed.dev/docs/api/generated/widgets.message.Class.Message

Get the inset height of the widget.

```APIDOC
## Get iheight

### Description
Retrieves the inset height of the widget.

### Method
GET

### Endpoint
widgets.message.Class.iheight

### Returns
`number` - The inset height.
```

--------------------------------

### Flexible Widget Positioning and Sizing

Source: https://unblessed.dev/docs/getting-started/quick-start

Illustrates using flexible units like percentages, 'center', and arithmetic expressions for positioning and sizing widgets within their parent containers.

```json
{
  "top": "center",      // Center vertically
  "left": "30%",        // 30% from left
  "width": "50%",       // 50% of parent width
  "height": "100%-6"    // Parent height minus 6 lines
}

```

--------------------------------

### iwidth

Source: https://unblessed.dev/docs/api/generated/widgets.message.Class.Message

Get the inset width of the widget.

```APIDOC
## Get iwidth

### Description
Retrieves the inset width of the widget.

### Method
GET

### Endpoint
widgets.message.Class.iwidth

### Returns
`number` - The inset width.
```

--------------------------------

### pick()

Source: https://unblessed.dev/docs/api/generated/widgets.list.Class.List

Show the list, focus it, select the first item, and wait for a selection. Callback receives the selected item text.

```APIDOC
## pick()

### Description
Show the list, focus it, select the first item, and wait for a selection. Callback receives the selected item text.

### Parameters
#### label
- `any` - Optional label to set while picking (or callback if label omitted)
#### callback?
- `any` - Callback function to receive selected item

### Returns
- `any`

### Example
```
list.pick("Select an option:", (err, value) => {
  console.log("Selected:", value);
});
```
```

--------------------------------

### _getCoords()

Source: https://unblessed.dev/docs/api/generated/widgets.filemanager.Class.FileManager

Gets the rendering coordinates of the widget.

```APIDOC
## _getCoords()

### Description
Gets the rendering coordinates of the widget.

### Parameters
- **get?** (boolean) - Optional parameter to get coordinates.
- **noscroll?** (boolean) - Optional parameter to ignore scroll.

### Returns
`RenderCoords` | `undefined` - The rendering coordinates or undefined if not available.
```

--------------------------------

### Pick Item from List with Callback

Source: https://unblessed.dev/docs/api/generated/widgets.list.Class.List

Use `pick` to display the list, focus it, select the first item, and wait for user selection. A callback function can be provided to handle the selected item, receiving an error and the selected value.

```javascript
list.pick("Select an option:", (err, value) => {
  console.log("Selected:", value);
});
```

--------------------------------

### tpadding

Source: https://unblessed.dev/docs/api/generated/widgets.filemanager.Class.FileManager

Gets the top padding of the widget.

```APIDOC
## tpadding

### Description
Gets the top padding of the widget.

### Method
GET

### Endpoint
Not applicable (getter method)

### Returns
`number` - The top padding value.
```

--------------------------------

### Adapt Layout with FitAddon and ResizeObserver

Source: https://unblessed.dev/docs/platforms/browser

Use the FitAddon to automatically resize the terminal to fit its container and a ResizeObserver to detect container size changes. Re-render the screen after fitting the terminal to ensure the display is up-to-date.

```javascript
const fitAddon = new FitAddon();
term.loadAddon(fitAddon);

const resizeObserver = new ResizeObserver(() => {
  fitAddon.fit();
  screen.render();
});

resizeObserver.observe(container);
```

--------------------------------

### lineHeight()

Source: https://unblessed.dev/docs/api/generated/lib.program.Class.Program

Gets the line height of the terminal.

```APIDOC
## lineHeight()

### Description
Gets the line height of the terminal.

### Method
`lineHeight()`

### Returns
`string` | `boolean` | `undefined`
```

--------------------------------

### iwidth

Source: https://unblessed.dev/docs/api/generated/widgets.filemanager.Class.FileManager

Gets the intrinsic width of the widget.

```APIDOC
## iwidth

### Description
Gets the intrinsic width of the widget.

### Method
GET

### Endpoint
Not applicable (getter method)

### Returns
`number` - The intrinsic width.
```

--------------------------------

### spawn

Source: https://unblessed.dev/docs/api/generated/widgets.overlayimage.Class.OverlayImage

Spawns a new process.

```APIDOC
## spawn(file, args, opt?, callback?)

### Description
Spawns a new process.

### Parameters
#### Path Parameters
- **file** (string) - Required - The file to execute.
- **args** (string[]) - Required - Arguments to pass to the file.
- **opt?** (any) - Optional - Options for the spawn.
- **callback?** (any) - Optional - Callback function.

#### Returns
`any`
```

--------------------------------

### pick(label, callback?)

Source: https://unblessed.dev/docs/api/generated/widgets.listtable.Class.ListTable

Show the list, focus it, select the first item, and wait for a selection. Callback receives the selected item text.

```APIDOC
## pick(label, callback?)

### Description
Show the list, focus it, select the first item, and wait for a selection. Callback receives the selected item text.

### Parameters
#### label
- `any` - Optional label to set while picking (or callback if label omitted)
#### callback?
- `any` - Callback function to receive selected item

### Returns
- `any`

### Example
```javascript
list.pick("Select an option:", (err, value) => {
  console.log("Selected:", value);
});
```
```

--------------------------------

### height

Source: https://unblessed.dev/docs/api/generated/widgets.filemanager.Class.FileManager

Gets or sets the height of the widget.

```APIDOC
## Get height

### Description
Gets the height of the widget.

### Method
GET

### Endpoint
widgets.filemanager.Class.height

### Returns
`number`
```

```APIDOC
## Set height

### Description
Sets the height of the widget.

### Method
SET

### Endpoint
widgets.filemanager.Class.height

### Parameters
#### Path Parameters
- **val** (any) - Required - The value to set for the height.

### Returns
`void`
```

--------------------------------

### width

Source: https://unblessed.dev/docs/api/generated/widgets.filemanager.Class.FileManager

Gets or sets the width of the widget.

```APIDOC
## Get width

### Description
Gets the width of the widget.

### Method
GET

### Endpoint
widgets.filemanager.Class.width

### Returns
`number`
```

```APIDOC
## Set width

### Description
Sets the width of the widget.

### Method
SET

### Endpoint
widgets.filemanager.Class.width

### Parameters
#### Path Parameters
- **val** (any) - Required - The value to set for the width.

### Returns
`void`
```

--------------------------------

### Button Constructor

Source: https://unblessed.dev/docs/api/generated/widgets.button.Class.Button

Initializes a new instance of the Button class. It accepts an optional options object.

```APIDOC
## Constructor

> **new Button**(`options`): `Button`

Defined in: packages/core/src/widgets/button.ts:20

#### Parameters​
##### options​
`ButtonOptions` = `{}`

#### Returns​
`Button`

#### Overrides​
`Input`.`constructor`
```

--------------------------------

### _detached

Source: https://unblessed.dev/docs/api/generated/widgets.filemanager.Class.FileManager

Gets the detached state of the widget.

```APIDOC
## Get _detached

### Description
Gets the detached state of the widget.

### Method
GET

### Endpoint
widgets.filemanager.Class._detached

### Returns
`boolean`
```

--------------------------------

### pick()

Source: https://unblessed.dev/docs/api/generated/widgets.filemanager.Class.FileManager

Pick a single file and return the path. Shows the file manager, waits for selection, then hides and returns result. Emits 'file' event when file is selected, 'cancel' event when cancelled.

```APIDOC
## pick()

### Description
Pick a single file and return the path. Shows the file manager, waits for selection, then hides and returns result. Emits 'file' event when file is selected, 'cancel' event when cancelled.

### Parameters
- **cwd?** (any) - Optional directory to start in (or callback if omitted)
- **callback?** (any) - Callback function receiving (err, filePath)

### Returns
`void`

### Example
```javascript
fileManager.pick((err, filePath) => {
  if (err) return console.error(err);
  if (filePath) console.log("Selected:", filePath);
});
```

### Overrides
`List.pick`
```

--------------------------------

### Loading Constructor

Source: https://unblessed.dev/docs/api/generated/widgets.loading.Class.Loading

Initializes a new instance of the Loading widget. It accepts an optional options object for configuration.

```APIDOC
## Constructor

### new Loading(options)

Defined in: packages/core/src/widgets/loading.ts:30

#### Parameters

##### options
`LoadingOptions` = `{}`

#### Returns

`Loading`

#### Overrides

`Box`.`constructor`
```

--------------------------------

### ibottom

Source: https://unblessed.dev/docs/api/generated/widgets.terminal.Class.Terminal

Gets the bottom inner coordinate of the widget.

```APIDOC
## ibottom

### Description
Gets the bottom inner coordinate of the widget.

### Get Signature
> **get** **ibottom**(): `number`
```

--------------------------------

### iright

Source: https://unblessed.dev/docs/api/generated/widgets.terminal.Class.Terminal

Gets the right inner coordinate of the widget.

```APIDOC
## iright

### Description
Gets the right inner coordinate of the widget.

### Get Signature
> **get** **iright**(): `number`
```

--------------------------------

### Choosing a Base Class for Custom Widgets

Source: https://unblessed.dev/docs/advanced/custom-widgets

Provides examples of extending Node, Element, and Box to create custom widgets with minimal features, layout capabilities, or full content and styling, respectively.

```typescript
// Extend Node for minimal widgets  
class TreeNode extends Node {  
  // Only tree structure and events  
}  
  
// Extend Element for layout widgets  
class Spacer extends Element {  
  // Positioning and sizing, no content  
}  
  
// Extend Box for content widgets  
class Badge extends Box {  
  // Full featured with content and styling  
}  

```

--------------------------------

### itop

Source: https://unblessed.dev/docs/api/generated/widgets.terminal.Class.Terminal

Gets the top inner coordinate of the widget.

```APIDOC
## itop

### Description
Gets the top inner coordinate of the widget.

### Get Signature
> **get** **itop**(): `number`
```

--------------------------------

### prompt.setInput

Source: https://unblessed.dev/docs/api/generated/widgets.prompt.Class.Prompt

Sets up a prompt for user input, aliasing the readInput functionality.

```APIDOC
## prompt.setInput

### Description
Sets up a prompt for user input, aliasing the readInput functionality.

### Signature
> **get** **setInput**(): (`text`, `value?`, `callback?`) => `void`

### Parameters
#### text
`string` - The message to display in the prompt.

#### value? (optional)
`string` | (`err`, `data`) => `void` - An initial value for the input field or a callback function.

#### callback? (optional)
(`err`, `data`) => `void` - A callback function that is executed after the user provides input.

### Returns
`void`

### Example
```javascript
prompt.setInput("Enter value:", (err, value) => {
  console.log(value);
});
```
```

--------------------------------

### ileft

Source: https://unblessed.dev/docs/api/generated/widgets.terminal.Class.Terminal

Gets the left inner coordinate of the widget.

```APIDOC
## ileft

### Description
Gets the left inner coordinate of the widget.

### Get Signature
> **get** **ileft**(): `number`
```

--------------------------------

### Line Constructor

Source: https://unblessed.dev/docs/api/generated/widgets.line.Class.Line

Initializes a new instance of the Line widget. It accepts an optional options object.

```APIDOC
## Constructor

> **new Line**(`options`): `Line`

Defined in: packages/core/src/widgets/line.ts:21

### Parameters

#### options

`LineOptions` = `{}`

### Returns

`Line`

### Overrides

`Box`.`constructor`
```

--------------------------------

### imageSize

Source: https://unblessed.dev/docs/api/generated/widgets.overlayimage.Class.OverlayImage

Gets the size of an image file in pixels.

```APIDOC
## imageSize(callback?)

### Description
Get the size of an image file in pixels.

### Parameters
#### Path Parameters
- **callback?** (any) - Optional - Optional callback function called with (err, size)

#### Returns
`any` - Operation result with image dimensions (raw, width, height)
```