Add title and titleAlignment options (#59)

Co-authored-by: Sindre Sorhus <[email protected]>

example.js

@@ -46,11 +46,16 @@ console.log('\n\n' + boxen(chalk.black('unicorn'), {
 }) + '\n');
 
 const sentences = 'Unbreakable_text_because_it_has_no_spaces '.repeat(5);
-console.log('\n\n' + boxen(sentences, {align: 'left'}) + '\n');
+console.log('\n\n' + boxen(sentences, {textAlignment: 'left'}) + '\n');
 
-console.log('\n\n' + boxen(sentences, {align: 'center'}) + '\n');
+console.log('\n\n' + boxen(sentences, {textAlignment: 'center'}) + '\n');
 
-console.log('\n\n' + boxen(sentences, {align: 'right', padding: {left: 1, right: 1, top: 0, bottom: 0}}) + '\n');
+console.log('\n\n' + boxen(sentences, {textAlignment: 'right', padding: {left: 1, right: 1, top: 0, bottom: 0}}) + '\n');
 
 const longWord = 'x'.repeat(process.stdout.columns + 20);
-console.log('\n\n' + boxen(longWord, {align: 'center'}) + '\n');
+console.log('\n\n' + boxen(longWord, {textAlignment: 'center'}) + '\n');
+
+const title = 'Beautiful title';
+console.log('\n\n' + boxen('This box has a nice title', {title}) + '\n');
+
+console.log('\n\n' + boxen('This box has a centered title', {title, titleAlignment: 'center'}) + '\n');

index.d.ts

@@ -121,8 +121,50 @@ declare namespace boxen {
 		Align the text in the box based on the widest line.
 
 		@default 'left'
+		@deprecated Use `textAlignment` instead.
 		*/
 		readonly align?: 'left' | 'right' | 'center';
+
+		/**
+		Align the text in the box based on the widest line.
+
+		@default 'left'
+		*/
+		readonly textAlignment?: 'left' | 'right' | 'center';
+
+		/**
+		Display a title at the top of the box.
+		If needed, the box will horizontally expand to fit the title.
+
+		@example
+		```
+		console.log(boxen('foo bar', {title: 'example'}));
+		// ┌ example ┐
+		// │foo bar  │
+		// └─────────┘
+		```
+		*/
+		readonly title?: string;
+
+		/**
+		Align the title in the top bar.
+
+		@default 'left'
+
+		@example
+		```
+		console.log(boxen('foo bar foo bar', {title: 'example', textAlignmentTitle: 'center'}));
+		// ┌─── example ───┐
+		// │foo bar foo bar│
+		// └───────────────┘
+
+		console.log(boxen('foo bar foo bar', {title: 'example', textAlignmentTitle: 'right'}));
+		// ┌────── example ┐
+		// │foo bar foo bar│
+		// └───────────────┘
+		```
+		*/
+		readonly titleAlignment?: 'left' | 'right' | 'center';
 	}
 }
 

index.js

@@ -9,7 +9,6 @@ const wrapAnsi = require('wrap-ansi');
 
 const NL = '\n';
 const PAD = ' ';
-const BORDERS_WIDTH = 2;
 
 const terminalColumns = () => {
 	const {env, stdout, stderr} = process;
@@ -75,6 +74,35 @@ const getBorderChars = borderStyle => {
 	return chararacters;
 };
 
+const makeTitle = (text, horizontal, alignement) => {
+	let title = '';
+
+	const textWidth = stringWidth(text);
+
+	switch (alignement) {
+		case 'left':
+			title = text + horizontal.slice(textWidth);
+			break;
+		case 'right':
+			title = horizontal.slice(textWidth) + text;
+			break;
+		default:
+			horizontal = horizontal.slice(textWidth);
+
+			if (horizontal.length % 2 === 1) { // This is needed in case the length is odd
+				horizontal = horizontal.slice(Math.floor(horizontal.length / 2));
+				title = horizontal.slice(1) + text + horizontal; // We reduce the left part of one character to avoid the bar to go beyond its limit
+			} else {
+				horizontal = horizontal.slice(horizontal.length / 2);
+				title = horizontal + text + horizontal;
+			}
+
+			break;
+	}
+
+	return title;
+};
+
 const makeContentText = (text, padding, columns, align) => {
 	text = ansiAlign(text, {align});
 	let lines = text.split(NL);
@@ -158,11 +186,19 @@ module.exports = (text, options) => {
 		padding: 0,
 		borderStyle: 'single',
 		dimBorder: false,
-		align: 'left',
+		textAlignment: 'left',
 		float: 'left',
+		titleAlignment: 'left',
 		...options
 	};
 
+	// This option is deprecated
+	if (options.align) {
+		options.textAlignment = options.align;
+	}
+
+	const BORDERS_WIDTH = 2;
+
 	if (options.borderColor && !isColorValid(options.borderColor)) {
 		throw new Error(`${options.borderColor} is not a valid borderColor`);
 	}
@@ -186,6 +222,18 @@ module.exports = (text, options) => {
 
 	let contentWidth = widestLine(wrapAnsi(text, columns - BORDERS_WIDTH, {hard: true})) + padding.left + padding.right;
 
+	// This prevents the title bar to exceed the console's width
+	let title = options.title && options.title.slice(0, columns - 4 - margin.left - margin.right);
+
+	if (title) {
+		title = ` ${title} `;
+	}
+
+	// Make the box larger to fit a larger title
+	if (stringWidth(title) > contentWidth) {
+		contentWidth = stringWidth(title);
+	}
+
 	if ((margin.left && margin.right) && contentWidth + BORDERS_WIDTH + margin.left + margin.right > columns) {
 		// Let's assume we have margins: left = 3, right = 5, in total = 8
 		const spaceForMargins = columns - contentWidth - BORDERS_WIDTH;
@@ -201,7 +249,7 @@ module.exports = (text, options) => {
 	// Prevent content from exceeding the console's width
 	contentWidth = Math.min(contentWidth, columns - BORDERS_WIDTH - margin.left - margin.right);
 
-	text = makeContentText(text, padding, contentWidth, options.align);
+	text = makeContentText(text, padding, contentWidth, options.textAlignment);
 
 	let marginLeft = PAD.repeat(margin.left);
 
@@ -214,7 +262,7 @@ module.exports = (text, options) => {
 	}
 
 	const horizontal = chars.horizontal.repeat(contentWidth);
-	const top = colorizeBorder(NL.repeat(margin.top) + marginLeft + chars.topLeft + horizontal + chars.topRight);
+	const top = colorizeBorder(NL.repeat(margin.top) + marginLeft + chars.topLeft + (title ? makeTitle(title, horizontal, options.titleAlignment) : horizontal) + chars.topRight);
 	const bottom = colorizeBorder(marginLeft + chars.bottomLeft + horizontal + chars.bottomRight + NL.repeat(margin.bottom));
 	const side = colorizeBorder(chars.vertical);
 

index.test-d.ts

@@ -19,6 +19,8 @@ const spacing: Spacing = {
 };
 
 expectType<string>(boxen('unicorns'));
+expectType<string>(boxen('unicorns', {title: 'title'}));
+expectType<string>(boxen('unicorns', {title: 'title', titleAlignment: 'center'}));
 expectType<string>(boxen('unicorns', {borderColor: 'green'}));
 expectType<string>(boxen('unicorns', {borderColor: '#ff0000'}));
 expectType<string>(boxen('unicorns', {borderStyle: 'double'}));
@@ -31,4 +33,4 @@ expectType<string>(boxen('unicorns', {margin: spacing}));
 expectType<string>(boxen('unicorns', {float: 'center'}));
 expectType<string>(boxen('unicorns', {backgroundColor: 'green'}));
 expectType<string>(boxen('unicorns', {backgroundColor: '#ff0000'}));
-expectType<string>(boxen('unicorns', {align: 'right'}));
+expectType<string>(boxen('unicorns', {textAlignment: 'right'}));

readme.md

@@ -34,6 +34,13 @@ console.log(boxen('unicorn', {padding: 1, margin: 1, borderStyle: 'double'}));
    ╚═════════════╝
 
 */
+
+console.log(boxen('unicorns love rainbows', {title: 'magical', titleAlignment: 'center'}));
+/*
+┌────── magical ───────┐
+│unicorns love rainbows│
+└──────────────────────┘
+*/
 ```
 
 ## API
@@ -127,6 +134,56 @@ Default: `false`
 
 Reduce opacity of the border.
 
+##### title
+
+Type: `string`
+
+Display a title at the top of the box.
+If needed, the box will horizontally expand to fit the title.
+
+Example:
+```js
+console.log(boxen('foo bar', {title: 'example'}));
+/*
+┌ example ┐
+│foo bar  │
+└─────────┘
+*/
+```
+
+##### titleAlignment
+
+Type: `string`\
+Default: `'left'`
+
+Align the title in the top bar.
+
+Values:
+- `'left'`
+```js
+/*
+┌ example ──────┐
+│foo bar foo bar│
+└───────────────┘
+*/
+```
+- `'center'`
+```js
+/*
+┌─── example ───┐
+│foo bar foo bar│
+└───────────────┘
+*/
+```
+- `'right'`
+```js
+/*
+┌────── example ┐
+│foo bar foo bar│
+└───────────────┘
+*/
+```
+
 ##### padding
 
 Type: `number | object`\
@@ -160,7 +217,7 @@ Values: `'black'` `'red'` `'green'` `'yellow'` `'blue'` `'magenta'` `'cyan'` `'w
 
 Color of the background.
 
-##### align
+##### textAlignment
 
 Type: `string`\
 Default: `'left'`\