box-em-up v1.0.0

Box Em' Up

Wrap your text on your terminal in a beautiful way

Install

npm install box-em-up

Usage

Box Em' Up provides an easy way to generate boxes using a simple import:

import boxEmUp from "box-em-up";

const template = [
	["Hello", "World"]
];

console.log(boxEmUp(template))
/*
┌───────────────────────────────────────────────────────────────────┬───────────────────────────────────────────────────────────────────┐
│ Hello                                                             │ World                                                             │
└───────────────────────────────────────────────────────────────────┴───────────────────────────────────────────────────────────────────┘
*/

const box = boxGen.generate(template, {
	maxWidth: 50, 
	overflow: "trim", 
	title: { content: "Top Line", align: "right", color: "rainbow4" }, 
	subtitle: { content: "Bottom Line", align: "left", color: "rainbow24"},
	colors: {
		grid: 0xff0000,
		text: 0x00ff00
	}
});

console.log(box);
/*
┌─────────────────────────────────────────────┬─────────────────────────────────── Top Line ┐
│ Hello                                       │ World                                       │
└ Bottom Line ────────────────────────────────┴─────────────────────────────────────────────┘
*/

And an easy way to customize your boxes using the box generation class:

import { BoxGenerator } from "box-em-up";
const boxGen = new BoxGenerator();

const customCharacterPreset: BoxCharacters = {
	"TopRight": "╗",
	"TopLeft": "╔",
	"BottomRight": "╝",
	"BottomLeft": "╚",
	"HorizontalSeparator": "═",
	"VerticalSeparator": "║",
	"TopJunction": "╦",
	"BottomJunction": "╩",
	"MiddleJunction": "╬",
	"LeftJunction": "╠",
	"RightJunction": "╣",
};
const index = boxGen.addPreset(customCharacterPreset);
boxGen.setPreset(index);

const template = [
	["Hello", "World"]
];

const box = boxGen.generate(template);
console.log(box);
/*
╔═══════════════════════════════════════════════════════════════════╦═══════════════════════════════════════════════════════════════════╗
║ Hello                                                             ║ World                                                             ║
╚═══════════════════════════════════════════════════════════════════╩═══════════════════════════════════════════════════════════════════╝
*/

API

Class: BoxGenerator

The class used to generate boxes.

[getter] characters(): BoxCharacters

Returns the currently loaded character set for the instance.

setPreset(index: number): boolean

Sets the character set to be used.

• index - number: The index of the preset to load.
• Returns: true if successfull, false otherwise.

addPreset(preset: BoxCharacters): boolean

Adds a new preset to the preset list of the instance.

• preset - BoxCharacters: A BoxCharacters structure containing the characters to be used.
• Returns: The index (number) of the preset on the preset list.

generate(template: BoxTemplate, options?: BoxGenOptions): string

Generates a box from a template.

• template - BoxTemplate: The template to be used to generate the box.
• options - BoxGenOptions (Optional): The options to be used to modify the generated box.
• Returns: A string containing the generated box.

Class: Separator

A helper class used to add horizontal separators to a box.

Interface: BoxCharacters

Represents a structure containing a character preset.

Any property in-between the % character represents a Helper type described below the properties section.

Properties:

• TopRight: string E.g: "┐"
• TopLeft: string E.g: "┌"
• BottomRight: string E.g: "┘"
• BottomLeft: string E.g: "└"
• HorizontalSeparator: string E.g: "─"
• VerticalSeparator: string E.g: "│"
• TopJunction: string E.g: "┬"
• BottomJunction: string E.g: "┴"
• MiddleJunction: string E.g: "┼"
• LeftJunction: string E.g: "├"
• RightJunction: string E.g: "┤"

Interface: BoxGenOptions

Represents a structure containing a set of options for box generation.

Any property in-between the % character represents a Helper type described below the properties section.

Properties:

• maxWidth (Optional): number The maximum width the grid should occupy, in characters
• overflow (Optional): "newline" | "trim" The overflow type to be used.
  • newline: Overflow should be broken intro a new line.
  • trim: Overflow will be trimmed and discarded.
• stripEmpty (Optional): boolean If enabled, all empty strings or strings with only whitespace will be removed.
• parseLineFeeds (Optional): boolean If enabled, all line feeds (\n) will be interpreted and the string will be divided into multiple lines, otherwise line feeds will be escaped.
• autocorrect (Optional): boolean If enabled, eventual errors due to misconfiguration will be automatically resolved, otherwise an error will be thrown.
• title (Optional):
  - One of: - ` { content: string, align?: "left" | "center" | "right", color?: %color% }

  		  ``` 
  		- `string`

The title to show above the grid.

• subtitle (Optional): - One of: - ` { content: string, align?: "left" | "center" | "right", color?: %color% }

  	  ``` 
  	- `string`

  The subtitle to show below the grid.
• colors (Optional):

  ```
  {
  	grid?: %color%
  	text?: %color%
  }
  ```

  The colors to be used on the box.

Helper types:

• color: One of:
  • number - A hexadecimal number representing an RGB color.
  • string:
    • A hexadecimal string representing an RGB color (must start with either # or 0x). - rainbow4, rainbow16, rainbow24, representing the 4-bit, 16-bit and 24-bit (truecolor) color sets. rainbow is an alias for rainbow4.

Type: BoxTemplate

Represents a template to be used as a source for box generation.

Structure:

• An array containing zero or more elements of either:
  • Separator
  • Sector[], where:
    • Sector - One of:
      • string - string[]

TODO

• Add the ability to automatically fit contents to border, removing unused whitespace.
• Add the ability to automatically join empty sectors.