tessl/npm-cliui

Easily create complex multi-column command-line interfaces with text formatting and layout capabilities

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

cliui

Name: tessl/npm-cliui
Author: tessl

cliui is a JavaScript/TypeScript library that enables creation of complex multi-column command-line interfaces with precise text formatting, alignment, and layout control. It provides a simple yet powerful API for arranging text in columns and rows with support for padding, borders, and intelligent text wrapping.

Package Information

Package Name: cliui
Package Type: npm
Language: JavaScript/TypeScript (ESM)
Installation: npm install cliui

Core Imports

import cliui from "cliui";

For CommonJS:

const cliui = require("cliui");

For Deno:

import cliui from "https://deno.land/x/cliui/deno.ts";

Basic Usage

import cliui from "cliui";

// Create a UI instance
const ui = cliui({ width: 80 });

// Add a simple row
ui.div("Usage: myapp [command] [options]");

// Add multi-column layout
ui.div(
  {
    text: "-f, --file",
    width: 20,
    padding: [0, 4, 0, 4]
  },
  {
    text: "the file to load (supports long descriptions with wrapping)",
    width: 40
  },
  {
    text: "[required]",
    align: "right"
  }
);

// Render to string
console.log(ui.toString());

Architecture

cliui is built around a core UI class that manages:

Column Layout System: Automatic width calculation and text distribution across columns
Text Processing: Integration with string-width, strip-ansi, and wrap-ansi for proper text handling
Layout DSL: Simple syntax using newlines and tabs for quick layouts
Alignment Engine: Left, right, and center text alignment within columns
Wrapping Logic: Intelligent text wrapping that respects ANSI escape codes

Capabilities

UI Creation

Create a UI instance with optional width and wrapping configuration.

/**
 * Creates a new UI instance for multi-column layouts
 * @param options - Configuration options for the UI
 * @returns UI instance with layout methods
 */
function cliui(options?: Partial<UIOptions>): UI;

interface UIOptions {
  /** Maximum width of the UI */
  width: number;
  /** Enable text wrapping (defaults to true) */
  wrap?: boolean;
  /** Initial rows (optional) */
  rows?: string[];
}

Column Layout

Create rows with multiple columns using div method.

/**
 * Creates a row with columns, supporting both string and object arguments
 * @param args - Columns as strings or column configuration objects
 * @returns ColumnArray for the created row
 */
div(...args: (Column | string)[]): ColumnArray;

interface Column {
  /** Text content for the column */
  text: string;
  /** Fixed width for the column (optional) */
  width?: number;
  /** Text alignment within the column */
  align?: "left" | "right" | "center";
  /** Padding as [top, right, bottom, left] */
  padding: number[];
  /** Whether to show border around column */
  border?: boolean;
}

interface ColumnArray extends Array<Column> {
  /** Whether this row should span (inline with previous row) */
  span: boolean;
}

Usage Examples:

// Simple single column
ui.div("Header text");

// Multiple columns with different configurations
ui.div(
  { text: "Left column", width: 20, align: "left" },
  "Middle column with automatic width",
  { text: "Right", align: "right" }
);

// With padding and borders
ui.div({
  text: "Bordered content",
  padding: [1, 2, 1, 2],
  border: true
});

Spanning Layout

Create rows that continue on the same line as the previous row.

/**
 * Creates a row like div, but attempts to render inline with previous row  
 * @param args - ColumnArray for the spanning row
 */
span(...args: ColumnArray): void;

Usage Example:

ui.div("Main content");
// Note: span takes a ColumnArray (result of div), though usage in practice
// suggests it should take individual arguments like div
const cols = ui.div({ text: "  continued on same line" });
ui.span(cols);

Layout DSL

Use special characters for quick text layouts without explicit column objects.

DSL Syntax:

\n - Creates new rows
\t - Creates new columns
Leading/trailing spaces - Create padding

// DSL example
ui.div(
  "Usage: myapp [command]\n" +
  "  --file\tspecify input file\n" +
  "  --output\tspecify output file\t[optional]"
);

Output Management

Control UI rendering and reset functionality.

/**
 * Renders the entire UI to a formatted string
 * @returns Multi-line string representation of the UI
 */
toString(): string;

/**
 * Clears all rows while maintaining width and wrap settings
 */
resetOutput(): void;

Usage Examples:

// Render UI
const output = ui.toString();
console.log(output);

// Clear and reuse
ui.resetOutput();
ui.div("New content");

Types

class UI {
  /** Maximum width of the UI */
  width: number;
  /** Whether text wrapping is enabled */
  wrap: boolean;
  /** Array of column rows */
  rows: ColumnArray[];
  
  constructor(opts: UIOptions);
  div(...args: (Column | string)[]): ColumnArray;
  span(...args: ColumnArray): void;
  resetOutput(): void;
  toString(): string;
}

interface UIOptions {
  width: number;
  wrap?: boolean;
  rows?: string[];
}

interface Column {
  text: string;
  width?: number;
  align?: "left" | "right" | "center";
  padding?: number[];
  border?: boolean;
}

interface ColumnArray extends Array<Column> {
  span: boolean;
}

Platform Support

Node.js: Full support via ESM (index.mjs) and CommonJS
Deno: Native support via deno.ts
TypeScript: Complete type definitions included
Browser: Not supported (requires Node.js dependencies)

Dependencies

cliui integrates with these packages for advanced text processing:

string-width: Measures text width accounting for ANSI escape codes
strip-ansi: Removes ANSI escape codes for measurement
wrap-ansi: Wraps text while preserving ANSI formatting

Install with Tessl CLI

npx tessl i tessl/npm-cliui

Workspace: tessl
Visibility: Public
Created: 6 months ago
Last updated: about 1 month ago
Describes: pkg:npm/cliui@9.0.x
Publish Source: CLI
Badge