terminal-richjs 0.1.0

package/README.md

@@ -0,0 +1,241 @@
+# RichJS
+
+**RichJS** is a TypeScript library for writing rich text (with color and style) to the terminal, and for displaying advanced content such as tables, markdown, and syntax highlighted code. It is heavily inspired by the popular [Python Rich](https://github.com/Textualize/rich) library.
+
+![License](https://img.shields.io/badge/license-MIT-blue.svg)
+![TypeScript](https://img.shields.io/badge/language-TypeScript-blue.svg)
+![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)
+
+## 📦 Installation
+
+```bash
+npm install richjs
+# or
+yarn add richjs
+# or
+pnpm add richjs
+```
+
+## 🚀 Quick Start
+
+The easiest way to get started is to import `Console` and print some text.
+
+```typescript
+import { Console } from 'richjs';
+
+const console = new Console();
+
+console.print('Hello, [bold magenta]World[/bold magenta]!');
+console.print('RichJS supports [italic]styles[/], emojis :rocket:, and more.');
+```
+
+## ✨ Features
+
+- **Rich Text**: Parse markup for color and style (`[red]bold[/red]`)
+- **Syntax Highlighting**: Token-based highlighting with multiple themes (Monokai, Dracula, GitHub, One Dark)
+- **Tables**: Auto-formatting tables with headers, footers, and zebra striping
+- **Progress Bars**: Multi-bar progress tracking with live updates and gradient colors
+- **Panels**: Bordered containers with titles, subtitles, and alignment options
+- **Tree Views**: Visualize hierarchical data with customizable guide styles
+- **Tracebacks**: Beautiful error traces with syntax-highlighted code snippets
+- **Markdown**: Render Markdown files directly to the terminal
+- **Layouts**: Split your terminal into flexible grids and rows/columns
+- **Logging**: Formatted log output with `RichHandler`
+
+## 🎨 Color Support
+
+RichJS supports multiple color formats:
+
+```typescript
+// Named colors
+console.print('[red]Red text[/red]');
+console.print('[bright_cyan]Bright cyan[/bright_cyan]');
+
+// Hex colors
+console.print('[#ff79c6]Dracula Pink[/#ff79c6]');
+console.print('[#50fa7b]Dracula Green[/#50fa7b]');
+
+// RGB colors
+console.print('[rgb(255,121,198)]Custom RGB[/rgb(255,121,198)]');
+
+// 256-color palette
+console.print('[color(196)]256-color red[/color(196)]');
+
+// Background colors
+console.print('[on #282a36]Dark background[/on #282a36]');
+```
+
+## 📊 Tables
+
+```typescript
+import { Console, Table } from 'richjs';
+
+const table = new Table({
+  title: 'Star Wars Movies',
+  box: 'rounded',
+  rowStyles: ['', 'dim'], // Zebra striping
+  caption: 'Box office data (USD)',
+});
+
+table.addColumn('Released', { justify: 'left' });
+table.addColumn('Title', { justify: 'left' });
+table.addColumn('Box Office', { justify: 'right' });
+
+table.addRow('1977', 'A New Hope', '$775,398,007');
+table.addRow('1980', 'The Empire Strikes Back', '$538,375,067');
+table.addRow('2015', 'The Force Awakens', '$2,068,223,624');
+
+new Console().print(table);
+```
+
+**Output:**
+
+```
+                    Star Wars Movies
+╭──────────┬─────────────────────────┬────────────────╮
+│ Released │ Title                   │     Box Office │
+├──────────┼─────────────────────────┼────────────────┤
+│ 1977     │ A New Hope              │   $775,398,007 │
+│ 1980     │ The Empire Strikes Back │   $538,375,067 │
+│ 2015     │ The Force Awakens       │ $2,068,223,624 │
+╰──────────┴─────────────────────────┴────────────────╯
+                  Box office data (USD)
+```
+
+## 💻 Syntax Highlighting
+
+```typescript
+import { Console, Syntax, Panel } from 'richjs';
+
+const code = `function fibonacci(n: number): number {
+  if (n <= 1) return n;
+  return fibonacci(n - 1) + fibonacci(n - 2);
+}`;
+
+const syntax = new Syntax(code, 'typescript', {
+  theme: 'monokai',
+  lineNumbers: true,
+  highlightLines: [3], // Highlight specific lines
+});
+
+new Console().print(
+  new Panel(syntax, {
+    title: 'Fibonacci',
+    titleAlign: 'left',
+  }),
+);
+```
+
+**Available themes:** `monokai`, `dracula`, `github`, `one-dark`
+
+## 🌳 Tree Views
+
+```typescript
+import { Console, Tree } from 'richjs';
+
+const tree = new Tree('📁 project');
+const src = tree.add('📁 src');
+src.add('📄 index.ts');
+src.add('📄 utils.ts');
+tree.add('📄 package.json');
+tree.add('📄 README.md');
+
+new Console().print(tree);
+```
+
+**Output:**
+
+```
+📁 project
+├── 📁 src
+│   ├── 📄 index.ts
+│   └── 📄 utils.ts
+├── 📄 package.json
+└── 📄 README.md
+```
+
+## 📦 Panels
+
+```typescript
+import { Console, Panel } from 'richjs';
+
+new Console().print(
+  new Panel('Hello, World!', {
+    title: 'Greeting',
+    titleAlign: 'left',
+    subtitle: 'A simple example',
+    subtitleAlign: 'right',
+    box: 'rounded',
+    borderStyle: 'cyan',
+  }),
+);
+```
+
+## 🚨 Tracebacks
+
+Beautiful error traces with syntax-highlighted code:
+
+```typescript
+import { installTracebackHandler } from 'richjs';
+
+// Install globally for all uncaught exceptions
+installTracebackHandler({
+  theme: 'monokai',
+  extraLines: 3,
+  suppressInternal: true,
+});
+
+// Or render manually
+import { Console, Traceback } from 'richjs';
+
+try {
+  throw new Error('Something went wrong');
+} catch (error) {
+  new Console().print(new Traceback(error));
+}
+```
+
+## 📈 Progress Bars
+
+```typescript
+import { Console, Progress, ProgressBar } from 'richjs';
+
+// Simple progress bar
+const bar = new ProgressBar(100, 75, {
+  completeStyle: '#61afef',
+  remainingStyle: 'dim',
+});
+new Console().print(bar);
+
+// Multi-task progress
+const progress = new Progress();
+const task1 = progress.addTask('Downloading', 100);
+const task2 = progress.addTask('Processing', 50);
+
+await progress.start(async () => {
+  while (!task1.completed) {
+    task1.advance(1);
+    await sleep(10);
+  }
+});
+```
+
+## 📚 Documentation
+
+See [DOCS.md](./DOCS.md) for comprehensive API documentation.
+
+## 🎯 Examples
+
+Run the visual demo:
+
+```bash
+npx tsx examples/visual-polish-demo.ts
+```
+
+## 🤝 Contributing
+
+Contributions are welcome! Please read our contributing guide.
+
+## 📄 License
+
+MIT