Add title and titleAlignment options

example.js

@@ -54,3 +54,8 @@ console.log('\n\n' + boxen(sentences, {align: 'right', padding: {left: 1, right:
 
 const longWord = 'x'.repeat(process.stdout.columns + 20);
 console.log('\n\n' + boxen(longWord, {align: '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, titleAlign: 'center'}) + '\n');

index.d.ts

@@ -123,6 +123,35 @@ declare namespace boxen {
 		@default 'left'
 		*/
 		readonly align?: 'left' | 'right' | 'center';
+
+		/**
+		Display a title on the top of the box.
+		If needed the box will enlarge to fit the title.
+
+		@example
+		```
+		console.log(boxen('foo bar foo bar', {title: 'title'}));
+		// ┌title──────────┐
+		// │foo bar foo bar│
+		// └───────────────┘
+		```
+		*/
+		readonly title?: string;
+
+		/**
+		The alignment of the box title.
+
+		@default 'left'
+
+		@example
+		```
+		console.log(boxen('foo bar foo bar', {title: 'title', alignTitle: 'right'}));
+		// ┌────────title┐
+		// │foo bar foo  │
+		// └─────────────┘
+		```
+		*/
+		readonly titleAlign?: '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);
@@ -160,9 +188,12 @@ module.exports = (text, options) => {
 		dimBorder: false,
 		align: 'left',
 		float: 'left',
+		titleAlign: 'left',
 		...options
 	};
 
+	const BORDERS_WIDTH = 2;
+
 	if (options.borderColor && !isColorValid(options.borderColor)) {
 		throw new Error(`${options.borderColor} is not a valid borderColor`);
 	}
@@ -186,6 +217,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;
@@ -214,7 +257,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.titleAlign) : 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', titleAlign: 'center'}));
 expectType<string>(boxen('unicorns', {borderColor: 'green'}));
 expectType<string>(boxen('unicorns', {borderColor: '#ff0000'}));
 expectType<string>(boxen('unicorns', {borderStyle: 'double'}));

readme.md

@@ -34,6 +34,13 @@ console.log(boxen('unicorn', {padding: 1, margin: 1, borderStyle: 'double'}));
    ╚═════════════╝
 
 */
+
+console.log(boxen('unicorns love rainbows', {title: 'rainbow', titleAlign: 'center'}));
+/*
+┌────── rainbow ───────┐
+│unicorns love rainbows│
+└──────────────────────┘
+*/
 ```
 
 ## API
@@ -127,6 +134,55 @@ Default: `false`
 
 Reduce opacity of the border.
 
+##### title
+
+Type: `string`
+
+Add a title to the box. If needed the box wil enlarge to fit the title.
+
+Example:
+```js
+console.log(boxen('foo bar', {title: 'example'}));
+/*
+┌ example ┐
+│foo bar  │
+└─────────┘
+*/
+```
+
+##### titleAlign
+
+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`\

test.js

@@ -16,6 +16,101 @@ test('creates a box', t => {
 	`);
 });
 
+test('title option', t => {
+	compare(t, boxen('foo', {title: 'title'}), `
+┌ title ┐
+│foo    │
+└───────┘
+	`);
+});
+
+test('title align center option', t => {
+	compare(t, boxen('foo bar foo bar', {
+		title: 'title',
+		titleAlign: 'center'
+	}), `
+┌──── title ────┐
+│foo bar foo bar│
+└───────────────┘
+	`);
+});
+
+test('title align right option', t => {
+	compare(t, boxen('foo bar foo bar', {
+		title: 'title',
+		titleAlign: 'right'
+	}), `
+┌──────── title ┐
+│foo bar foo bar│
+└───────────────┘
+	`);
+});
+
+test('title and text align', t => {
+	compare(t, boxen('Hello !\nThis text is on the right\nAmazing!', {
+		title: 'title',
+		align: 'right'
+	}), `
+┌ title ──────────────────┐
+│                  Hello !│
+│This text is on the right│
+│                 Amazing!│
+└─────────────────────────┘
+	`);
+});
+
+test('box size adapts to title length', t => {
+	compare(t, 	boxen('Hello !\nThis text is on the center\nAmazing!\nIt stretched to the title length.', {
+		title: 'This is a very large title with many words in it',
+		align: 'center'
+	}), `
+┌ This is a very large title with many words in it ┐
+│                     Hello !                      │
+│           This text is on the center             │
+│                    Amazing!                      │
+│        It stretched to the title length.         │
+└──────────────────────────────────────────────────┘
+	`);
+});
+
+test('title with align and text padding', t => {
+	compare(t, 	boxen('Hello !\nAll the text here is on the right\nEven the title.\nAmazing padding too ;)', {
+		title: 'This is a title',
+		titleAlign: 'right',
+		align: 'right',
+		padding: 2
+	}), `
+┌──────────────────────────── This is a title ┐
+│                                             │
+│                                             │
+│                                Hello !      │
+│      All the text here is on the right      │
+│                        Even the title.      │
+│                 Amazing padding too ;)      │
+│                                             │
+│                                             │
+└─────────────────────────────────────────────┘
+	`);
+});
+
+test('title with align, padding and margin', t => {
+	compare(t, 	boxen('Hello !\nThis text has padding and margin.\nCentered too !', {
+		title: 'This is a title',
+		titleAlign: 'center',
+		align: 'center',
+		margin: 1,
+		padding: 1
+	}), `
+   ┌─────────── This is a title ───────────┐
+   │                                       │
+   │                Hello !                │
+   │   This text has padding and margin.   │
+   │            Centered too !             │
+   │                                       │
+   └───────────────────────────────────────┘
+	`);
+});
+
 test('padding option', t => {
 	compare(t, boxen('foo', {padding: 2}), `
 ┌───────────────┐