npm package: @selfteachme/boxerjs
Description: A utility for drawing beautiful boxes around terminal content
Latest version: 1.0.0

# @selfteachme/boxerjs

A beautiful and flexible utility for drawing boxes around terminal content. Perfect for CLI applications using yargs and chalk.

## Features

- Draw boxes around any text content
- Flexible width options: content-based, fixed, or terminal width
- Text alignment options: left, center, or right
- Customizable padding and margins
- Custom border styles and colors using chalk
- Full TypeScript support
- Compatible with yargs and chalk

## Installation

```bash
npm install @selfteachme/boxerjs chalk
# If you're using yargs
npm install yargs
```

## Usage

### Basic Example

```typescript
import { Box } from '@selfteachme/boxerjs';
import chalk from 'chalk';

const box = new Box({
  content: 'Hello, World!',
  color: chalk.green,
  borderColor: chalk.blue
});

console.log(box.toString());
```

Output:
```
╭───────────────╮
│ Hello, World! │
╰───────────────╯
```

### Terminal-width Box with Alignment

```typescript
const box = new Box({
  content: 'Centered text in a terminal-width box',
  width: 'terminal',
  align: 'center',  // 'left', 'center', or 'right'
  padding: [1, 2],
  color: chalk.yellow
});

console.log(box.toString());
```

Output:
```
╭──────────────────────────────────────────────────────────────╮
│                                                              │
│            Centered text in a terminal-width box             │
│                                                              │
╰──────────────────────────────────────────────────────────────╯
```

### With Yargs

```typescript
import yargs from 'yargs';
import { Box } from '@selfteachme/boxerjs';
import chalk from 'chalk';

yargs
  .command({
    command: 'greet <name>',
    describe: 'Greet someone with a fancy box',
    builder: {
      color: {
        describe: 'Text color',
        type: 'string',
        default: 'green'
      },
      align: {
        describe: 'Text alignment',
        choices: ['left', 'center', 'right'],
        default: 'left'
      }
    },
    handler: (argv) => {
      const box = new Box({
        content: `Hello, ${argv.name}!`,
        width: 'terminal',
        align: argv.align,
        color: chalk[argv.color],
        padding: [1, 2],
        margin: [1, 0]
      });
      
      console.log(box.toString());
    }
  })
  .argv;
```

### Advanced Options

```typescript
const box = new Box({
  content: 'Multi-line\ncontent example',
  width: 'terminal',     // or 'content' or fixed number
  align: 'center',       // or 'left' or 'right'
  padding: [1, 2],       // [vertical, horizontal] or single number
  margin: [1, 2],        // [vertical, horizontal] or single number
  color: chalk.green,
  borderColor: chalk.blue,
  style: {
    topLeft: '╔',
    topRight: '╗',
    bottomLeft: '╚',
    bottomRight: '╝',
    horizontal: '═',
    vertical: '║'
  }
});
```

## API Reference

### BoxOptions

| Option | Type | Description |
|--------|------|-------------|
| content | string | The text content to wrap in a box |
| width | 'content' \| 'terminal' \| number | Box width strategy (default: 'content') |
| align | 'left' \| 'center' \| 'right' | Text alignment within the box (default: 'left') |
| padding | number \| [number, number] | Inner padding [vertical, horizontal] (default: 0) |
| margin | number \| [number, number] | Outer margin [vertical, horizontal] (default: 0) |
| style | BoxStyle | Custom border characters |
| color | chalk.Chalk | Text color using chalk |
| borderColor | chalk.Chalk | Border color using chalk |

### BoxStyle

| Property | Default | Description |
|----------|---------|-------------|
| topLeft | '╭' | Top-left corner character |
| topRight | '╮' | Top-right corner character |
| bottomLeft | '╰' | Bottom-left corner character |
| bottomRight | '╯' | Bottom-right corner character |
| horizontal | '─' | Horizontal border character |
| vertical | '│' | Vertical border character |

## License

MIT