terminal-richjs 0.1.1 → 0.2.1

package/README.md

@@ -1,6 +1,6 @@
-# RichJS
+# terminal-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.
+**terminal-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)
@@ -18,33 +18,160 @@ pnpm add terminal-richjs
 
 ## 🚀 Quick Start
 
-The easiest way to get started is to import `Console` and print some text.
-
 ```typescript
-import { Console } from 'terminal-richjs';
+import { Console, replaceEmoji } from 'terminal-richjs';
 
 const console = new Console();
 
 console.print('Hello, [bold magenta]World[/bold magenta]!');
-console.print('RichJS supports [italic]styles[/], emojis :rocket:, and more.');
+console.print(replaceEmoji('RichJS supports emojis :rocket: and styles :sparkles:'));
 ```
 
 ## ✨ 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`
+| Feature                 | Description                                                   |
+| ----------------------- | ------------------------------------------------------------- |
+| **Rich Text**           | Parse markup for color and style (`[red]bold[/red]`)          |
+| **Emoji Shortcodes**    | 174 emojis like `:rocket:` → 🚀, `:heart:` → ❤️               |
+| **JSON Rendering**      | Pretty-printed, syntax-highlighted JSON output                |
+| **Columns Layout**      | Responsive multi-column displays                              |
+| **Spinners**            | 45 animated spinner styles (dots, stars, moon, hearts...)     |
+| **Live Display**        | Real-time terminal updates                                    |
+| **Status Indicator**    | Animated spinners with messages                               |
+| **Syntax Highlighting** | Token-based highlighting (Monokai, Dracula, GitHub, One Dark) |
+| **Tables**              | Auto-formatting with headers, footers, zebra striping         |
+| **Progress Bars**       | Multi-bar progress with gradient colors                       |
+| **Panels**              | Bordered containers with titles and subtitles                 |
+| **Tree Views**          | Hierarchical data with customizable guide styles              |
+| **Tracebacks**          | Beautiful error traces with code snippets                     |
+| **Markdown**            | Render Markdown files to the terminal                         |
+| **Layouts**             | Split terminal into flexible grids                            |
+| **Logging**             | Formatted log output with `RichHandler`                       |
+
+---
+
+## 🎯 Emoji Shortcodes
 
-## 🎨 Color Support
+```typescript
+import { replaceEmoji, EMOJI, listEmoji } from 'terminal-richjs';
+
+// Replace shortcodes in text
+console.log(replaceEmoji('Hello :wave: World :rocket:'));
+// Output: Hello 👋 World 🚀
+
+// Access emoji directly
+console.log(EMOJI['fire']); // 🔥
+console.log(EMOJI['heart']); // ❤️
+
+// List all available emojis (174 total)
+console.log(listEmoji().slice(0, 10));
+// ['rocket', 'star', 'fire', 'heart', 'check', 'warning', ...]
+```
+
+**Popular shortcodes:** `:rocket:` 🚀, `:fire:` 🔥, `:heart:` ❤️, `:star:` ⭐, `:check:` ✅, `:warning:` ⚠️, `:sparkles:` ✨, `:party:` 🎉, `:coffee:` ☕, `:bug:` 🐛
+
+---
+
+## 📋 JSON Pretty Printing
+
+```typescript
+import { Console, JSON, Panel } from 'terminal-richjs';
+
+const data = {
+  name: 'terminal-richjs',
+  version: '0.2.0',
+  features: ['emoji', 'json', 'columns', 'spinners'],
+  config: { theme: 'dracula', colors: true },
+};
+
+new Console().print(
+  new Panel(JSON.fromData(data, { sortKeys: true }), { title: 'package.json', box: 'rounded' }),
+);
+```
+
+Options: `indent`, `sortKeys`, `highlight`
+
+---
 
-RichJS supports multiple color formats:
+## 🎨 Columns Layout
+
+```typescript
+import { Console, Columns } from 'terminal-richjs';
+
+const files = [
+  '📁 src',
+  '📁 dist',
+  '📁 node_modules',
+  '📄 package.json',
+  '📄 tsconfig.json',
+  '📄 README.md',
+  '📄 LICENSE',
+  '📁 examples',
+];
+
+new Console().print(new Columns(files, { padding: 2, equal: true }));
+```
+
+**Output:**
+
+```
+📁 src            📁 dist           📁 node_modules
+📄 package.json   📄 tsconfig.json  📄 README.md
+📄 LICENSE        📁 examples
+```
+
+Options: `width`, `padding`, `equal`, `columnFirst`, `rightToLeft`
+
+---
+
+## ⚙️ Spinners (45 Styles)
+
+```typescript
+import { Spinner, listSpinners, Status, sleep } from 'terminal-richjs';
+
+// Create a spinner
+const spinner = new Spinner('dots', { text: 'Loading...', style: 'green' });
+console.log(spinner.getCurrentFrame());
+
+// Available spinners
+console.log(listSpinners());
+// ['dots', 'dots2', 'line', 'star', 'moon', 'hearts', 'clock', 'earth', ...]
+
+// Status indicator (animated)
+const status = new Status('Processing...', { spinnerName: 'dots' });
+status.start();
+await sleep(2000);
+status.update('Almost done...');
+await sleep(1000);
+status.stop();
+```
+
+---
+
+## ⚡ Live Display
+
+```typescript
+import { Live, sleep, Style, replaceEmoji } from 'terminal-richjs';
+
+const live = new Live();
+
+await live.start(async (update) => {
+  for (let i = 0; i <= 100; i++) {
+    const filled = Math.floor(i / 5);
+    const remaining = 20 - filled;
+    const bar =
+      Style.parse('#50fa7b').apply('━'.repeat(filled)) +
+      Style.parse('#3a3a3a dim').apply('━'.repeat(remaining));
+
+    update(replaceEmoji(`:rocket: Processing... ${bar} ${i}%`));
+    await sleep(50);
+  }
+});
+```
+
+---
+
+## 🎨 Color Support
 
 ```typescript
 // Named colors
@@ -53,7 +180,6 @@ 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)]');
@@ -65,6 +191,8 @@ console.print('[color(196)]256-color red[/color(196)]');
 console.print('[on #282a36]Dark background[/on #282a36]');
 ```
 
+---
+
 ## 📊 Tables
 
 ```typescript
@@ -74,7 +202,6 @@ const table = new Table({
   title: 'Star Wars Movies',
   box: 'rounded',
   rowStyles: ['', 'dim'], // Zebra striping
-  caption: 'Box office data (USD)',
 });
 
 table.addColumn('Released', { justify: 'left' });
@@ -88,19 +215,7 @@ 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
 
@@ -115,18 +230,15 @@ const code = `function fibonacci(n: number): number {
 const syntax = new Syntax(code, 'typescript', {
   theme: 'monokai',
   lineNumbers: true,
-  highlightLines: [3], // Highlight specific lines
+  highlightLines: [3],
 });
 
-new Console().print(
-  new Panel(syntax, {
-    title: 'Fibonacci',
-    titleAlign: 'left',
-  }),
-);
+new Console().print(new Panel(syntax, { title: 'Fibonacci' }));
 ```
 
-**Available themes:** `monokai`, `dracula`, `github`, `one-dark`
+**Themes:** `monokai`, `dracula`, `github`, `one-dark`
+
+---
 
 ## 🌳 Tree Views
 
@@ -138,7 +250,6 @@ 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);
 ```
@@ -150,10 +261,11 @@ new Console().print(tree);
 ├── 📁 src
 │   ├── 📄 index.ts
 │   └── 📄 utils.ts
-├── 📄 package.json
-└── 📄 README.md
+└── 📄 package.json
 ```
 
+---
+
 ## 📦 Panels
 
 ```typescript
@@ -164,30 +276,23 @@ new Console().print(
     title: 'Greeting',
     titleAlign: 'left',
     subtitle: 'A simple example',
-    subtitleAlign: 'right',
     box: 'rounded',
     borderStyle: 'cyan',
   }),
 );
 ```
 
-## 🚨 Tracebacks
+---
 
-Beautiful error traces with syntax-highlighted code:
+## 🚨 Tracebacks
 
 ```typescript
-import { installTracebackHandler } from 'terminal-richjs';
+import { installTracebackHandler, Console, Traceback } from 'terminal-richjs';
 
-// Install globally for all uncaught exceptions
-installTracebackHandler({
-  theme: 'monokai',
-  extraLines: 3,
-  suppressInternal: true,
-});
+// Install globally
+installTracebackHandler({ theme: 'monokai', extraLines: 3 });
 
 // Or render manually
-import { Console, Traceback } from 'terminal-richjs';
-
 try {
   throw new Error('Something went wrong');
 } catch (error) {
@@ -195,43 +300,90 @@ try {
 }
 ```
 
-## 📈 Progress Bars
+---
 
-```typescript
-import { Console, Progress, ProgressBar } from 'terminal-richjs';
+## 🎯 Examples
 
-// Simple progress bar
-const bar = new ProgressBar(100, 75, {
-  completeStyle: '#61afef',
-  remainingStyle: 'dim',
-});
-new Console().print(bar);
+Run the demos:
 
-// Multi-task progress
-const progress = new Progress();
-const task1 = progress.addTask('Downloading', 100);
-const task2 = progress.addTask('Processing', 50);
+```bash
+# New features demo (Emoji, JSON, Columns, Spinners, Live)
+npx tsx examples/new-features-demo.ts
 
-await progress.start(async () => {
-  while (!task1.completed) {
-    task1.advance(1);
-    await sleep(10);
-  }
-});
+# Full visual demo
+npx tsx examples/visual-polish-demo.ts
 ```
 
-## 📚 Documentation
+---
 
-See [DOCS.md](./DOCS.md) for comprehensive API documentation.
-
-## 🎯 Examples
+## 📚 API Reference
 
-Run the visual demo:
+### Core Exports
 
-```bash
-npx tsx examples/visual-polish-demo.ts
+```typescript
+import {
+  // Core
+  Console,
+  Style,
+  Segment,
+  MarkupParser,
+
+  // Renderables
+  Panel,
+  Table,
+  Tree,
+  Rule,
+  Text,
+  Padding,
+  Align,
+  Columns,
+  JSON,
+  Syntax,
+  Markdown,
+
+  // Progress & Status
+  Progress,
+  ProgressBar,
+  Spinner,
+  Status,
+  Live,
+  sleep,
+
+  // Emoji
+  replaceEmoji,
+  EMOJI,
+  listEmoji,
+  hasEmoji,
+
+  // Spinners
+  SPINNERS,
+  listSpinners,
+  getSpinner,
+
+  // Themes
+  Theme,
+  MONOKAI,
+  DRACULA,
+  GITHUB_LIGHT,
+  ONE_DARK,
+
+  // Utilities
+  Color,
+  getBox,
+  listBoxStyles,
+
+  // Error handling
+  Traceback,
+  installTracebackHandler,
+
+  // Logging
+  RichHandler,
+  Logger,
+} from 'terminal-richjs';
 ```
 
+---
+
 ## 🤝 Contributing
 
 Contributions are welcome! Please read our contributing guide.